mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-22 21:11:14 +00:00
feat(service-identity): register through the dialect of the running release
Registration now goes through a registration dialect module: the paths of the challenge and the registration, the bytes scrypt runs over and the body and headers of the request. Each stable release will carry the dialect the TREK services issuer writes for it; until the first such release the module speaks the original registration, so nothing changes on the wire. An issuer that no longer takes the release's dialect answers 410. TREK then says so once per process, waits a day (or what Retry-After asks) and keeps searching through the shared pool. The issuer client only lets a dialect register at the issuer's own paths, with X-TREK-* headers that are not the gate's and a body of registration size. Renewal needs no dialect, and an expired key may now be renewed for a year instead of 30 days, the same period the issuer allows, so an installation that was offline for long comes back without an update. The key format ignores the new optional dialect claim; the shared vectors gain one key that carries it.
This commit is contained in:
@@ -1,3 +1,8 @@
|
||||
# Written by scripts/generate-entities.ts and held byte for byte to its output
|
||||
# by check:entities, so Prettier must not rewrite them.
|
||||
src/db/entities/
|
||||
|
||||
# Written by the TREK services issuer and committed as it wrote them: the
|
||||
# registration dialect (taken over by the release job) and the issuer's sample.
|
||||
src/nest/service-identity/registration-dialect.ts
|
||||
tests/fixtures/service-identity/registration-dialect.sample.ts
|
||||
|
||||
@@ -16,7 +16,8 @@
|
||||
* npm run lint:format -- --update take formatted and deleted files off the list;
|
||||
* it never adds one
|
||||
*
|
||||
* src/db/entities/ is generated and checked by check:entities instead.
|
||||
* src/db/entities/ is generated and checked by check:entities instead, and the
|
||||
* registration dialect is written by the TREK services issuer for each release.
|
||||
*
|
||||
* To format a file: npx prettier --write <file>. The comparison lives in
|
||||
* scripts/lib/format.mjs at the repository root; Prettier and its config come
|
||||
@@ -33,12 +34,19 @@ const root = fileURLToPath(new URL('..', import.meta.url));
|
||||
// byte to its output by check:entities, so their layout is the generator's, not
|
||||
// Prettier's. .prettierignore keeps `npm run format` off them for the same reason.
|
||||
const GENERATED = 'src/db/entities/';
|
||||
// The registration dialect and the issuer's sample of one are written by the
|
||||
// TREK services issuer and committed as it wrote them (the release job takes
|
||||
// the dialect over unchanged), so their layout is the issuer's generator's.
|
||||
const ISSUER_WRITTEN = [
|
||||
'src/nest/service-identity/registration-dialect.ts',
|
||||
'tests/fixtures/service-identity/registration-dialect.sample.ts',
|
||||
];
|
||||
await runCli('lint:format', (args) =>
|
||||
check({
|
||||
prettier,
|
||||
root,
|
||||
dirs: ['src', 'tests'],
|
||||
accepts: (key) => key.endsWith('.ts') && !key.startsWith(GENERATED),
|
||||
accepts: (key) => key.endsWith('.ts') && !key.startsWith(GENERATED) && !ISSUER_WRITTEN.includes(key),
|
||||
update: args.includes('--update'),
|
||||
list: args.includes('--list'),
|
||||
}),
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { safeFetch } from '../../utils/ssrfGuard';
|
||||
import type { RegistrationRequest } from './registration-dialect.types';
|
||||
import { SERVICE_ISSUER_ORIGIN } from './service-identity.constants';
|
||||
import { retryAfterMs, serverDateMs } from './service-identity.helpers';
|
||||
import { serviceUserAgent } from './user-agent';
|
||||
@@ -18,18 +19,27 @@ const TIMEOUT_MS = 10_000;
|
||||
/** Every answer of the issuer is a few hundred bytes. */
|
||||
const MAX_BYTES = 4096;
|
||||
|
||||
/*
|
||||
* What a registration dialect may ask of a request. The dialect module is
|
||||
* written by the issuer, so it is held to the paths the issuer serves, to
|
||||
* headers of its own and to a small body; anything else is refused before it
|
||||
* leaves. scripts/ci/check-registration-dialect.mjs applies the same rules to
|
||||
* a new dialect in the release job.
|
||||
*/
|
||||
const CHALLENGE_PATH = /^\/v1\/register(\/[A-Za-z0-9_-]{12})?\/challenge$/;
|
||||
const REGISTER_PATH = /^\/v1\/register(\/[A-Za-z0-9_-]{12})?$/;
|
||||
const DIALECT_HEADER = /^X-TREK-[A-Za-z0-9-]{1,40}$/;
|
||||
/** The headers the gate itself answers with or reads; a dialect never sends them. */
|
||||
const RESERVED_HEADER = /^X-TREK-(Install|Tier|Legacy|Quota|Instance|Notice)(-|$)/i;
|
||||
const HEADER_VALUE = /^[\x20-\x7e]{1,256}$/;
|
||||
const MAX_REGISTRATION_BYTES = 2048;
|
||||
|
||||
export interface IssuerAnswer<T> {
|
||||
body: T;
|
||||
/** The issuer's clock from its Date header. */
|
||||
serverMs: number | null;
|
||||
}
|
||||
|
||||
interface RegistrationRequest {
|
||||
c: string;
|
||||
nonce: string;
|
||||
v: string;
|
||||
}
|
||||
|
||||
/** A refusal of the issuer, with how long it asked to be left alone. */
|
||||
export class IssuerError extends Error {
|
||||
constructor(
|
||||
@@ -45,12 +55,18 @@ export class IssuerError extends Error {
|
||||
/** The calls TREK makes to the key issuer at places.liketrek.com, and the allowance any liketrek host reports. */
|
||||
@Injectable()
|
||||
export class IssuerClient {
|
||||
challenge(): Promise<IssuerAnswer<ServiceChallenge>> {
|
||||
return this.call('GET', '/v1/register/challenge', serviceChallengeSchema);
|
||||
/** A challenge to solve, at the path of the dialect this build registers in. */
|
||||
challenge(path = '/v1/register/challenge'): Promise<IssuerAnswer<ServiceChallenge>> {
|
||||
if (!CHALLENGE_PATH.test(path)) {
|
||||
return Promise.reject(new Error('the registration dialect asks for a challenge elsewhere'));
|
||||
}
|
||||
return this.call('GET', path, serviceChallengeSchema);
|
||||
}
|
||||
|
||||
register(request: RegistrationRequest): Promise<IssuerAnswer<ServiceKeyGrant>> {
|
||||
return this.call('POST', '/v1/register', serviceKeyGrantSchema, { body: request });
|
||||
register(path: string, request: RegistrationRequest): Promise<IssuerAnswer<ServiceKeyGrant>> {
|
||||
const refusal = registrationRefusal(path, request);
|
||||
if (refusal) return Promise.reject(new Error(`the registration dialect ${refusal}`));
|
||||
return this.call('POST', path, serviceKeyGrantSchema, { body: request.body, headers: request.headers });
|
||||
}
|
||||
|
||||
renew(key: string): Promise<IssuerAnswer<ServiceKeyGrant>> {
|
||||
@@ -69,9 +85,18 @@ export class IssuerClient {
|
||||
method: 'GET' | 'POST',
|
||||
path: string,
|
||||
schema: z.ZodType<T>,
|
||||
opts: { body?: RegistrationRequest; bearer?: string | null; origin?: string } = {},
|
||||
opts: {
|
||||
body?: Record<string, unknown>;
|
||||
headers?: Record<string, string>;
|
||||
bearer?: string | null;
|
||||
origin?: string;
|
||||
} = {},
|
||||
): Promise<IssuerAnswer<T>> {
|
||||
const headers: Record<string, string> = { Accept: 'application/json', 'User-Agent': serviceUserAgent() };
|
||||
const headers: Record<string, string> = {
|
||||
...opts.headers,
|
||||
Accept: 'application/json',
|
||||
'User-Agent': serviceUserAgent(),
|
||||
};
|
||||
if (opts.bearer) headers.Authorization = `Bearer ${opts.bearer}`;
|
||||
if (opts.body) headers['Content-Type'] = 'application/json';
|
||||
const res = await safeFetch(
|
||||
@@ -89,3 +114,17 @@ export class IssuerClient {
|
||||
return { body: schema.parse(await res.json()), serverMs };
|
||||
}
|
||||
}
|
||||
|
||||
/** Why a dialect's registration may not go out, or null when it may. */
|
||||
function registrationRefusal(path: string, request: RegistrationRequest): string | null {
|
||||
if (!REGISTER_PATH.test(path)) return 'registers elsewhere';
|
||||
if (!Object.entries(request.headers).every(isDialectHeader)) return 'sends a header TREK does not send';
|
||||
if (Buffer.byteLength(JSON.stringify(request.body), 'utf8') > MAX_REGISTRATION_BYTES) {
|
||||
return 'sends a body larger than a registration';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function isDialectHeader([name, value]: [string, string]): boolean {
|
||||
return DIALECT_HEADER.test(name) && !RESERVED_HEADER.test(name) && HEADER_VALUE.test(value);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
/**
|
||||
* How this build of TREK registers with the TREK services.
|
||||
*
|
||||
* Each stable release replaces this file with the one the issuer writes for
|
||||
* its version, in the version bump commit (.github/workflows/docker.yml); its
|
||||
* layout is then the generator's, so Prettier leaves it alone. Until the first
|
||||
* such release it speaks the original registration, which the issuer accepts
|
||||
* for a transition period. Renewing a key never goes through this file: an
|
||||
* installation keeps its key whatever release it runs. After a stable release,
|
||||
* merge main into dev so that dev and prerelease builds register with the
|
||||
* current dialect.
|
||||
*
|
||||
* The dialect is the registration's, not SQL's; lint:dialect has nothing to
|
||||
* look for here.
|
||||
*/
|
||||
import type { DialectSelfCheck, RegistrationDialect } from './registration-dialect.types';
|
||||
|
||||
const DIALECT = '0';
|
||||
const SALT = Buffer.from('trek-pow-v1', 'utf8');
|
||||
|
||||
export const registrationDialect: RegistrationDialect = {
|
||||
id: DIALECT,
|
||||
releasedFor: 'dev',
|
||||
createdAt: '2026-10-29',
|
||||
challengePath: '/v1/register/challenge',
|
||||
registerPath: '/v1/register',
|
||||
begin({ challenge, version }) {
|
||||
return {
|
||||
work(nonce) {
|
||||
return { password: Buffer.from(`${challenge.c}.${nonce}`, 'utf8'), salt: SALT };
|
||||
},
|
||||
request(nonce) {
|
||||
return { body: { c: challenge.c, nonce: String(nonce), v: version }, headers: {} };
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
|
||||
/** Fixed inputs and what this module must make of them; TREK's tests and release job run it. */
|
||||
export const SELF_CHECK: DialectSelfCheck = {
|
||||
challenge: { c: 'v1.selfcheck.0', alg: 'scrypt', N: 16, r: 1, p: 1, bits: 0, expires_at: 1 },
|
||||
version: 'dev',
|
||||
random: '000102030405060708090a0b0c0d0e0f',
|
||||
nowSeconds: 1800000000,
|
||||
nonce: 41,
|
||||
passwordSha256: '6da395852966856653d9efba4dd3230e31f0fa325558474c91ae719247cc20ac',
|
||||
saltSha256: '9a4f2641b36f212d95eeceb212ce3587672322074288da20da4822809816aa7b',
|
||||
scrypt: 'f3de9aab4d5d9e114d63ba51bb0c8f007a644c1e24ef7b8e4062d49e9eed5376',
|
||||
requestSha256: '840dd80c265fba34a73ff4927eaa8416aa344d32372bf4d85273bf5ce130af99',
|
||||
};
|
||||
@@ -0,0 +1,72 @@
|
||||
/**
|
||||
* The shape of a registration dialect: how one release of TREK turns a
|
||||
* challenge of the issuer into a proof of work and a registration request.
|
||||
*
|
||||
* Each release registers in a dialect of its own, written by the issuer and
|
||||
* committed as registration-dialect.ts with the version bump. This file is the
|
||||
* stable side of that contract: the generated module imports these types, and
|
||||
* the key service only ever talks to a dialect through them. Renewing a key
|
||||
* never goes through a dialect.
|
||||
*/
|
||||
import type { ServiceChallenge } from '@trek/shared';
|
||||
|
||||
/** What a dialect gets to work with for one registration. */
|
||||
export interface DialectInputs {
|
||||
challenge: ServiceChallenge;
|
||||
/** The running version, at most 32 characters. */
|
||||
version: string;
|
||||
/** 16 random bytes, fresh for every registration and never stored. */
|
||||
random: Buffer;
|
||||
/** Unix seconds on the issuer's clock. */
|
||||
nowSeconds: number;
|
||||
}
|
||||
|
||||
/** What scrypt runs over for one nonce. */
|
||||
export interface ProofInput {
|
||||
password: Buffer;
|
||||
salt: Buffer;
|
||||
}
|
||||
|
||||
/** The registration as it goes out: the JSON body and the extra X-TREK-* headers. */
|
||||
export interface RegistrationRequest {
|
||||
body: Record<string, unknown>;
|
||||
headers: Record<string, string>;
|
||||
}
|
||||
|
||||
/** One registration in progress. A nonce runs from 0 to 2^40. */
|
||||
export interface DialectAttempt {
|
||||
work(nonce: number): ProofInput;
|
||||
request(nonce: number): RegistrationRequest;
|
||||
}
|
||||
|
||||
export interface RegistrationDialect {
|
||||
/** '0' for the original registration, otherwise the issuer's 12-character id. */
|
||||
id: string;
|
||||
/** The release the issuer wrote the dialect for. */
|
||||
releasedFor: string;
|
||||
/** YYYY-MM-DD; the issuer accepts a dialect for new registrations for 180 days from then. */
|
||||
createdAt: string;
|
||||
challengePath: string;
|
||||
registerPath: string;
|
||||
begin(inputs: DialectInputs): DialectAttempt;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fixed inputs and what the dialect must make of them, as the issuer computed
|
||||
* it. The password, the salt and the request are compared by their SHA-256
|
||||
* (the request as JSON.stringify({ body, headers })); scrypt runs with the
|
||||
* challenge's N=16, r=1, p=1 and 32 bytes of output.
|
||||
*/
|
||||
export interface DialectSelfCheck {
|
||||
challenge: ServiceChallenge;
|
||||
version: string;
|
||||
/** Hex. */
|
||||
random: string;
|
||||
nowSeconds: number;
|
||||
nonce: number;
|
||||
passwordSha256: string;
|
||||
saltSha256: string;
|
||||
/** Hex. */
|
||||
scrypt: string;
|
||||
requestSha256: string;
|
||||
}
|
||||
@@ -1,2 +1,5 @@
|
||||
/** The issuer of installation keys: the Places host itself, so no new egress domain is needed. */
|
||||
export const SERVICE_ISSUER_ORIGIN = 'https://places.liketrek.com';
|
||||
|
||||
/** The registration dialect this build speaks (registration-dialect.ts); tests hand in their own. */
|
||||
export const REGISTRATION_DIALECT = Symbol('REGISTRATION_DIALECT');
|
||||
|
||||
@@ -4,7 +4,9 @@ import { SchedulingModule } from '../scheduling/scheduling.module';
|
||||
import { SettingsModule } from '../settings/settings.module';
|
||||
import { IssuerClient } from './issuer.client';
|
||||
import { QuotaTracker } from './quota-tracker';
|
||||
import { registrationDialect } from './registration-dialect';
|
||||
import { ServiceClock } from './service-clock';
|
||||
import { REGISTRATION_DIALECT } from './service-identity.constants';
|
||||
import { ServiceIdentityController } from './service-identity.controller';
|
||||
import { ServiceIdentityPort, serviceIdentitySlot } from './service-identity.interface';
|
||||
import { ServiceIdentityService } from './service-identity.service';
|
||||
@@ -33,6 +35,7 @@ import { Module, type OnModuleDestroy } from '@nestjs/common';
|
||||
ServiceKeyService,
|
||||
ServiceKeyStore,
|
||||
{ provide: ServiceIdentityPort, useClass: ServiceRequestIdentity },
|
||||
{ provide: REGISTRATION_DIALECT, useValue: registrationDialect },
|
||||
],
|
||||
exports: [ServiceIdentityPort],
|
||||
})
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
import type { DialectAttempt, ProofInput } from './registration-dialect.types';
|
||||
import type { ServiceChallenge } from '@trek/shared';
|
||||
|
||||
import { scrypt } from 'node:crypto';
|
||||
|
||||
const SALT = 'trek-pow-v1';
|
||||
const HASH_BYTES = 32;
|
||||
|
||||
type ScryptCost = Pick<ServiceChallenge, 'N' | 'r' | 'p'>;
|
||||
|
||||
/** scrypt(c + "." + nonce, "trek-pow-v1"), off the event loop. */
|
||||
export function powHash(challenge: string, nonce: string, cost: ScryptCost): Promise<Buffer> {
|
||||
/** scrypt over what the dialect made of one nonce, off the event loop. */
|
||||
export function powHash(input: ProofInput, cost: ScryptCost): Promise<Buffer> {
|
||||
const { N, r, p } = cost;
|
||||
// Twice what scrypt needs, so Node's 32 MB default never refuses a valid challenge.
|
||||
const maxmem = 2 * 128 * N * r + 128 * r * p;
|
||||
return new Promise((resolve, reject) => {
|
||||
scrypt(`${challenge}.${nonce}`, SALT, HASH_BYTES, { N, r, p, maxmem }, (err, hash) =>
|
||||
scrypt(input.password, input.salt, HASH_BYTES, { N, r, p, maxmem }, (err, hash) =>
|
||||
err ? reject(err) : resolve(hash),
|
||||
);
|
||||
});
|
||||
@@ -28,14 +28,19 @@ export function leadingZeroBits(hash: Uint8Array): number {
|
||||
return bits;
|
||||
}
|
||||
|
||||
/** The first decimal nonce whose hash has at least `bits` leading zero bits, tried until `deadlineMs`. */
|
||||
export function solvePow(challenge: ServiceChallenge, deadlineMs: number): Promise<string> {
|
||||
return firstNonceFrom(0, challenge, deadlineMs);
|
||||
/** The first nonce whose hash has at least `bits` leading zero bits, tried until `deadlineMs`. */
|
||||
export function solvePow(challenge: ServiceChallenge, attempt: DialectAttempt, deadlineMs: number): Promise<number> {
|
||||
return firstNonceFrom(0, challenge, attempt, deadlineMs);
|
||||
}
|
||||
|
||||
async function firstNonceFrom(nonce: number, challenge: ServiceChallenge, deadlineMs: number): Promise<string> {
|
||||
async function firstNonceFrom(
|
||||
nonce: number,
|
||||
challenge: ServiceChallenge,
|
||||
attempt: DialectAttempt,
|
||||
deadlineMs: number,
|
||||
): Promise<number> {
|
||||
if (Date.now() >= deadlineMs) throw new Error('the registration challenge expired before it was solved');
|
||||
const hash = await powHash(challenge.c, String(nonce), challenge);
|
||||
if (leadingZeroBits(hash) >= challenge.bits) return String(nonce);
|
||||
return firstNonceFrom(nonce + 1, challenge, deadlineMs);
|
||||
const hash = await powHash(attempt.work(nonce), challenge);
|
||||
if (leadingZeroBits(hash) >= challenge.bits) return nonce;
|
||||
return firstNonceFrom(nonce + 1, challenge, attempt, deadlineMs);
|
||||
}
|
||||
|
||||
@@ -6,8 +6,9 @@ import { conflict } from '../common/domain-error';
|
||||
import { withRequestContext } from '../database/request-context';
|
||||
import { IssuerClient, IssuerError, type IssuerAnswer } from './issuer.client';
|
||||
import { RefusalStreak } from './refusal-streak';
|
||||
import type { RegistrationDialect } from './registration-dialect.types';
|
||||
import { ServiceClock } from './service-clock';
|
||||
import { SERVICE_ISSUER_ORIGIN } from './service-identity.constants';
|
||||
import { REGISTRATION_DIALECT, SERVICE_ISSUER_ORIGIN } from './service-identity.constants';
|
||||
import { isAllowlisted, keyFingerprint, sameServiceUrl } from './service-identity.helpers';
|
||||
import { parseServiceKey, type ServiceKey } from './service-key.format';
|
||||
import { solvePow } from './service-key.pow';
|
||||
@@ -17,13 +18,20 @@ import { Inject, Injectable } from '@nestjs/common';
|
||||
import type { ConfigType } from '@nestjs/config';
|
||||
import type { ServiceIdentityState, ServiceKeyGrant } from '@trek/shared';
|
||||
|
||||
import { randomInt } from 'node:crypto';
|
||||
import { randomBytes, randomInt } from 'node:crypto';
|
||||
|
||||
const DAY_SECONDS = 86_400;
|
||||
/** A key is renewed from day 60 of its 90, unless the issuer said otherwise. */
|
||||
const RENEW_AGE_SECONDS = 60 * DAY_SECONDS;
|
||||
/** An expired key can still be renewed for this long; after that it registers anew. */
|
||||
const RENEW_GRACE_SECONDS = 30 * DAY_SECONDS;
|
||||
/**
|
||||
* An expired key can still be renewed for this long; after that it registers
|
||||
* anew. Renewing needs no dialect, so an installation that was offline for up
|
||||
* to a year past its key's expiry comes back without an update. The issuer
|
||||
* allows the same period; the two move together.
|
||||
*/
|
||||
const RENEW_GRACE_SECONDS = 365 * DAY_SECONDS;
|
||||
/** How long to leave the issuer alone after it no longer takes this release's dialect, unless it says. */
|
||||
const DIALECT_REFUSED_WAIT_MS = 24 * 3_600_000;
|
||||
/** Spreads the new registrations of every installation a broken key hit, instead of all at once. */
|
||||
const REREGISTER_JITTER_MS = 6 * 3_600_000;
|
||||
const FIRST_BACKOFF_MS = 5 * 60_000;
|
||||
@@ -57,6 +65,7 @@ export class ServiceKeyService {
|
||||
private registering = false;
|
||||
private nextAttemptAt = 0;
|
||||
private failures = 0;
|
||||
private dialectRefusalLogged = false;
|
||||
private readonly refusals = new RefusalStreak();
|
||||
|
||||
constructor(
|
||||
@@ -66,6 +75,7 @@ export class ServiceKeyService {
|
||||
private readonly issuer: IssuerClient,
|
||||
private readonly clock: ServiceClock,
|
||||
private readonly orm: MikroORM,
|
||||
@Inject(REGISTRATION_DIALECT) private readonly dialect: RegistrationDialect,
|
||||
) {}
|
||||
|
||||
/** Whether the Places service this instance uses is one the key goes to. */
|
||||
@@ -262,6 +272,10 @@ export class ServiceKeyService {
|
||||
this.failures = 0;
|
||||
logInfo('TREK services: this installation is registered.');
|
||||
} catch (err) {
|
||||
if (err instanceof IssuerError && err.status === 410) {
|
||||
this.dialectRefused(err);
|
||||
return;
|
||||
}
|
||||
this.backOff(err);
|
||||
throw err;
|
||||
} finally {
|
||||
@@ -284,10 +298,32 @@ export class ServiceKeyService {
|
||||
}
|
||||
|
||||
private async solveChallenge(): Promise<IssuerAnswer<ServiceKeyGrant>> {
|
||||
const challenge = await this.issuer.challenge();
|
||||
const challenge = await this.issuer.challenge(this.dialect.challengePath);
|
||||
this.clock.learn(challenge.serverMs);
|
||||
const nonce = await solvePow(challenge.body, this.clock.toLocalMs(challenge.body.expires_at));
|
||||
return this.issuer.register({ c: challenge.body.c, nonce, v: runningVersion() });
|
||||
const attempt = this.dialect.begin({
|
||||
challenge: challenge.body,
|
||||
version: runningVersion().slice(0, 32),
|
||||
random: randomBytes(16),
|
||||
nowSeconds: this.clock.nowSeconds(),
|
||||
});
|
||||
const nonce = await solvePow(challenge.body, attempt, this.clock.toLocalMs(challenge.body.expires_at));
|
||||
return this.issuer.register(this.dialect.registerPath, attempt.request(nonce));
|
||||
}
|
||||
|
||||
/**
|
||||
* The issuer no longer takes new registrations in this release's dialect.
|
||||
* Nothing is wrong with the installation, and nothing it can do about it but
|
||||
* an update, so this is said once per process and asked again a day later;
|
||||
* until then requests go through the shared pool as without a key.
|
||||
*/
|
||||
private dialectRefused(err: IssuerError): void {
|
||||
this.nextAttemptAt = Date.now() + (err.retryAfterMs ?? DIALECT_REFUSED_WAIT_MS);
|
||||
if (this.dialectRefusalLogged) return;
|
||||
this.dialectRefusalLogged = true;
|
||||
logWarn(
|
||||
'TREK services: this release can no longer register with the TREK services. Searches and routes ' +
|
||||
'continue through the shared pool and the public services; updating TREK restores the key.',
|
||||
);
|
||||
}
|
||||
|
||||
/** Same installation, new expiry; the old key is the proof, so no proof of work. */
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
/**
|
||||
* How TREK 9.9.9 registers with the TREK services.
|
||||
*
|
||||
* The issuer writes this file for each release and the release pipeline
|
||||
* commits it with the version bump. It is not edited by hand, and its layout
|
||||
* is the generator's, so Prettier leaves it alone. Renewing a key never goes
|
||||
* through it: an installation keeps its key whatever release it runs. After a
|
||||
* stable release, merge main into dev so that dev and prerelease builds
|
||||
* register with the current dialect.
|
||||
*
|
||||
* The dialect is the registration's, not SQL's; lint:dialect has nothing to
|
||||
* look for here.
|
||||
*/
|
||||
import type { DialectSelfCheck, RegistrationDialect } from './registration-dialect.types';
|
||||
|
||||
import { createHash, createHmac, hkdfSync, pbkdf2Sync } from 'node:crypto';
|
||||
import { crc32 } from 'node:zlib';
|
||||
|
||||
const DIALECT = 'KitchenSink0';
|
||||
const CONSTANT = Buffer.from('206ebd4ad98b5f9c3531195aa89f6285612c396a98999a127b7972b6eefe03a8', 'hex');
|
||||
|
||||
const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
|
||||
|
||||
function u32be(value: number): Buffer {
|
||||
const out = Buffer.alloc(4);
|
||||
out.writeUInt32BE(value >>> 0);
|
||||
return out;
|
||||
}
|
||||
|
||||
function u32le(value: number): Buffer {
|
||||
const out = Buffer.alloc(4);
|
||||
out.writeUInt32LE(value >>> 0);
|
||||
return out;
|
||||
}
|
||||
|
||||
function u64be(value: number): Buffer {
|
||||
const out = Buffer.alloc(8);
|
||||
out.writeBigUInt64BE(BigInt(value));
|
||||
return out;
|
||||
}
|
||||
|
||||
function u64le(value: number): Buffer {
|
||||
const out = Buffer.alloc(8);
|
||||
out.writeBigUInt64LE(BigInt(value));
|
||||
return out;
|
||||
}
|
||||
|
||||
function leb128(value: number): Buffer {
|
||||
const out: number[] = [];
|
||||
let rest = value;
|
||||
do {
|
||||
const low = rest % 128;
|
||||
rest = Math.floor(rest / 128);
|
||||
out.push(low | (Math.sign(rest) << 7));
|
||||
} while (rest > 0);
|
||||
return Buffer.from(out);
|
||||
}
|
||||
|
||||
function lp32le(part: Buffer): Buffer {
|
||||
const head = Buffer.alloc(4);
|
||||
head.writeUInt32LE(part.length);
|
||||
return Buffer.concat([head, part]);
|
||||
}
|
||||
|
||||
function base32(input: Buffer): string {
|
||||
const bits = [...input].map((byte) => byte.toString(2).padStart(8, '0')).join('');
|
||||
let out = '';
|
||||
for (let i = 0; i < bits.length; i += 5) {
|
||||
out += BASE32.charAt(parseInt(bits.slice(i, i + 5).padEnd(5, '0'), 2));
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function reverseBlocks(input: Buffer, width: number): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
for (let i = 0; i + width <= out.length; i += width) out.subarray(i, i + width).reverse();
|
||||
return out;
|
||||
}
|
||||
|
||||
function permute(input: Buffer, order: number[]): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
order.forEach((from, to) => out.writeUInt8(input.readUInt8(from), to));
|
||||
return out;
|
||||
}
|
||||
|
||||
function fold(input: Buffer, size: number): Buffer {
|
||||
const out = Buffer.alloc(size);
|
||||
input.forEach((byte, i) => out.writeUInt8(out.readUInt8(i % size) ^ byte, i % size));
|
||||
return out;
|
||||
}
|
||||
|
||||
function interleave(a: Buffer, b: Buffer): Buffer {
|
||||
const parts: Buffer[] = [];
|
||||
for (let i = 0; i < Math.max(a.length, b.length); i++) parts.push(a.subarray(i, i + 1), b.subarray(i, i + 1));
|
||||
return Buffer.concat(parts);
|
||||
}
|
||||
|
||||
function mixWordsBe(input: Buffer, rotation: number, consts: Buffer): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
let previous = 0;
|
||||
for (let i = 0; i + 4 <= out.length; i += 4) {
|
||||
const word = (out.readUInt32BE(i) + consts.readUInt32BE(i % consts.length)) >>> 0;
|
||||
previous = (((word << rotation) | (word >>> (32 - rotation))) ^ previous) >>> 0;
|
||||
out.writeUInt32BE(previous, i);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function mixWordsLe(input: Buffer, rotation: number, consts: Buffer): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
let previous = 0;
|
||||
for (let i = 0; i + 4 <= out.length; i += 4) {
|
||||
const word = (out.readUInt32LE(i) + consts.readUInt32BE(i % consts.length)) >>> 0;
|
||||
previous = (((word << rotation) | (word >>> (32 - rotation))) ^ previous) >>> 0;
|
||||
out.writeUInt32LE(previous, i);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function keystream8be(input: Buffer, start: number): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
for (let offset = 0; offset < out.length; offset += 32) {
|
||||
const counter = Buffer.from([(start + offset / 32) & 0xff]);
|
||||
const block = createHash('sha256').update(CONSTANT).update(counter).digest();
|
||||
for (let j = offset; j < Math.min(offset + 32, out.length); j++) {
|
||||
out.writeUInt8(out.readUInt8(j) ^ block.readUInt8(j - offset), j);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function keystream16le(input: Buffer, start: number): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
for (let offset = 0; offset < out.length; offset += 32) {
|
||||
const counter = Buffer.alloc(2);
|
||||
counter.writeUInt16LE((start + offset / 32) & 0xffff);
|
||||
const block = createHash('sha256').update(CONSTANT).update(counter).digest();
|
||||
for (let j = offset; j < Math.min(offset + 32, out.length); j++) {
|
||||
out.writeUInt8(out.readUInt8(j) ^ block.readUInt8(j - offset), j);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function keystream32be(input: Buffer, start: number): Buffer {
|
||||
const out = Buffer.from(input);
|
||||
for (let offset = 0; offset < out.length; offset += 32) {
|
||||
const counter = Buffer.alloc(4);
|
||||
counter.writeUInt32BE((start + offset / 32) >>> 0);
|
||||
const block = createHash('sha256').update(CONSTANT).update(counter).digest();
|
||||
for (let j = offset; j < Math.min(offset + 32, out.length); j++) {
|
||||
out.writeUInt8(out.readUInt8(j) ^ block.readUInt8(j - offset), j);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export const registrationDialect: RegistrationDialect = {
|
||||
id: DIALECT,
|
||||
releasedFor: '9.9.9',
|
||||
createdAt: '2026-01-01',
|
||||
challengePath: `/v1/register/${DIALECT}/challenge`,
|
||||
registerPath: `/v1/register/${DIALECT}`,
|
||||
begin({ challenge, version, random, nowSeconds }) {
|
||||
const c = Buffer.from(challenge.c, 'utf8');
|
||||
const v = Buffer.from(version, 'utf8');
|
||||
const hc = createHash('sha256').update(c).digest();
|
||||
const salt1 = Buffer.concat([
|
||||
CONSTANT.subarray(0, 8),
|
||||
Buffer.from([0x1f]),
|
||||
hc,
|
||||
Buffer.from([0x1f]),
|
||||
c.subarray(3, 19),
|
||||
]);
|
||||
const salt2 = createHash('shake256', { outputLength: 24 }).update(salt1).digest();
|
||||
const salt3 = pbkdf2Sync(salt2, random, 3, 32, 'sha512');
|
||||
const salt4 = Buffer.from(hkdfSync('sha384', salt3, hc.subarray(0, 16), Buffer.from('a1b2c3d4e5', 'hex'), 40));
|
||||
const salt5 = createHmac('sha3-256', CONSTANT).update(salt4).digest();
|
||||
const salt6 = fold(salt5, 20);
|
||||
const salt7Words = Buffer.from('deadbeef0badf00d', 'hex');
|
||||
const salt7 = mixWordsBe(salt6, 5, salt7Words);
|
||||
const salt8 = Buffer.concat([random.subarray(2, 9), salt7]);
|
||||
const salt9 = Buffer.from(salt8.toString('base64url'), 'utf8');
|
||||
return {
|
||||
work(nonce) {
|
||||
const pass1 = Buffer.concat([
|
||||
lp32le(c),
|
||||
lp32le(leb128(nonce)),
|
||||
lp32le(v),
|
||||
lp32le(random),
|
||||
lp32le(u32le(nowSeconds)),
|
||||
lp32le(u64le(nonce)),
|
||||
lp32le(hc.subarray(3, 19)),
|
||||
]);
|
||||
const pass2 = createHash('blake2b512').update(pass1).digest();
|
||||
const pass3Words = Buffer.from('9e3779b97f4a7c1501234567', 'hex');
|
||||
const pass3 = mixWordsLe(mixWordsLe(pass2, 7, pass3Words), 13, pass3Words);
|
||||
const pass4 = keystream16le(pass3, 5);
|
||||
const pass5 = Buffer.concat([pass4.subarray(9 % pass4.length), pass4.subarray(0, 9 % pass4.length)]);
|
||||
const pass6 = reverseBlocks(pass5, 4);
|
||||
const pass7 = permute(pass6, [3, 0, 15, 7, 1, 2, 4, 6, 5, 8, 9, 11, 10, 13, 12, 14]);
|
||||
const pass8 = Buffer.from(pass7.map((byte) => (byte * 37 + 11) & 0xff));
|
||||
const pass9 = interleave(pass8, CONSTANT);
|
||||
const pass10 = Buffer.concat([pass9, u32be(crc32(pass9))]);
|
||||
const pass11 = Buffer.from(pass10.toString('hex'), 'utf8');
|
||||
const pass12 = Buffer.concat([pass11, Buffer.from([0x3a]), v]);
|
||||
const pass13 = Buffer.from(base32(pass12), 'utf8');
|
||||
const pass14 = pass13.subarray(10, 58);
|
||||
return { password: pass14, salt: salt9 };
|
||||
},
|
||||
request(nonce) {
|
||||
const seal1 = Buffer.concat([
|
||||
v,
|
||||
Buffer.from(String(nonce), 'utf8'),
|
||||
Buffer.from(String(nowSeconds), 'utf8'),
|
||||
c,
|
||||
random,
|
||||
u64be(nonce),
|
||||
u32be(nowSeconds),
|
||||
Buffer.from(nonce.toString(16), 'utf8'),
|
||||
]);
|
||||
const seal2 = createHmac('sha512', seal1).update(CONSTANT).digest();
|
||||
const seal3 = Buffer.from(seal2.toString('base64'), 'utf8');
|
||||
const seal4 = createHash('sha384').update(seal3).digest();
|
||||
const seal5 = Buffer.from(seal4.toString('hex').toUpperCase(), 'utf8');
|
||||
const seal6 = Buffer.from(seal5).reverse();
|
||||
const seal7 = keystream32be(seal6, 200);
|
||||
const seal8 = interleave(seal7, hc).subarray(0, seal7.length);
|
||||
const seal9 = Buffer.concat([seal8, u32le(crc32(seal8))]);
|
||||
const seal10 = keystream8be(seal9, 1);
|
||||
const seal11 = seal10.subarray(8, 40);
|
||||
return {
|
||||
body: {
|
||||
'ferry-passage': {
|
||||
'release-mark': version,
|
||||
tide: 'amber-41',
|
||||
'ticket-stamp': challenge.c,
|
||||
harbor: nonce.toString(16),
|
||||
'gull-wing': 'slate-7',
|
||||
lantern: base32(random),
|
||||
compass: nowSeconds,
|
||||
},
|
||||
},
|
||||
headers: { 'X-TREK-Ferry-Seal': seal11.toString('base64url') },
|
||||
};
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
|
||||
/** Fixed inputs and what this module must make of them; TREK's tests and release job run it. */
|
||||
export const SELF_CHECK: DialectSelfCheck = {
|
||||
challenge: { c: 'v1.selfcheck.KitchenSink0', alg: 'scrypt', N: 16, r: 1, p: 1, bits: 0, expires_at: 1 },
|
||||
version: '9.9.9',
|
||||
random: '000102030405060708090a0b0c0d0e0f',
|
||||
nowSeconds: 1800000000,
|
||||
nonce: 41,
|
||||
passwordSha256: '7b2c79ba69f022e031c4db19ff0bdf1f67bed98498a73ed747f968d346bc3110',
|
||||
saltSha256: '552659da096a9c393d520721f1aa26e5d3716305f4a6167effb13b9e7660e737',
|
||||
scrypt: '611e71acba947b2fffb86a831d4f389c8f72f5182d7bde30d4bb1f5c3abac730',
|
||||
requestSha256: '3df6e9c6fb70e039a2cd072cb526e975c996e6e6618ded4c89e09f6a7440c4f4',
|
||||
};
|
||||
@@ -0,0 +1,10 @@
|
||||
/**
|
||||
* The sample dialect beside this file is the issuer's own test output, kept
|
||||
* byte for byte, and imports its types from next to itself the way a real
|
||||
* dialect does in src/nest/service-identity/. This points that import at the
|
||||
* real types, so the sample is typechecked and linted against them.
|
||||
*/
|
||||
export type {
|
||||
DialectSelfCheck,
|
||||
RegistrationDialect,
|
||||
} from '../../../src/nest/service-identity/registration-dialect.types';
|
||||
@@ -28,6 +28,19 @@
|
||||
"token": "tk1.test1.eyJpIjoiRUJFU0V4UVZGaGNZR1JvYkhCMGVIdyIsImlhdCI6MTc5MzAwMDAwMCwiZXhwIjoxODAwNzc2MDAwLCJxIjoib3duIn0.VQcnAlqeWD6BvPR0hfqyEM0Hri154soKz2dtYOEE8SY8Kt08oRV0Q4PbS-phJ2JZxisLLfIYndbdwnsM-WwFDQ",
|
||||
"valid": true
|
||||
},
|
||||
{
|
||||
"name": "std_with_dialect",
|
||||
"payload": {
|
||||
"i": "ICEiIyQlJicoKSorLC0uLw",
|
||||
"iat": 1793000000,
|
||||
"exp": 1800776000,
|
||||
"q": "std",
|
||||
"d": "KitchenSink0"
|
||||
},
|
||||
"payload_json": "{\"i\":\"ICEiIyQlJicoKSorLC0uLw\",\"iat\":1793000000,\"exp\":1800776000,\"q\":\"std\",\"d\":\"KitchenSink0\"}",
|
||||
"token": "tk1.test1.eyJpIjoiSUNFaUl5UWxKaWNvS1NvckxDMHVMdyIsImlhdCI6MTc5MzAwMDAwMCwiZXhwIjoxODAwNzc2MDAwLCJxIjoic3RkIiwiZCI6IktpdGNoZW5TaW5rMCJ9.B_Xw8kLVvXOwhzotyxvsBFR0aNpXmUWXXT_4LjjdCXyiAEFIxy_wGkgWqCClFdCwhNJnDe_SeaDjS4DLf6upAQ",
|
||||
"valid": true
|
||||
},
|
||||
{
|
||||
"name": "tampered_signature",
|
||||
"token": "tk1.test1.eyJpIjoiQUFFQ0F3UUZCZ2NJQ1FvTERBME9EdyIsImlhdCI6MTc5MzAwMDAwMCwiZXhwIjoxODAwNzc2MDAwLCJxIjoic3RkIn0.UiQGzHwmtYj4s93PR6l5kqAsbEAZwURmhVlhljanHRTBB-FAE_20rbLWLsAlRQNn5faeigKXpFX_ZV5Ulr53BQ",
|
||||
|
||||
@@ -43,7 +43,8 @@ describe('IssuerClient', () => {
|
||||
|
||||
it('SIISS-002: registers with the solved challenge and the version as JSON', async () => {
|
||||
safeFetch.mockResolvedValueOnce(json(GRANT, 201));
|
||||
expect((await issuer.register({ c: 'v1.x', nonce: '17', v: '5.1.0' })).body).toEqual(GRANT);
|
||||
const request = { body: { c: 'v1.x', nonce: '17', v: '5.1.0' }, headers: {} };
|
||||
expect((await issuer.register('/v1/register', request)).body).toEqual(GRANT);
|
||||
const { url, init } = lastCall();
|
||||
expect(url).toBe('https://places.liketrek.com/v1/register');
|
||||
expect(init.method).toBe('POST');
|
||||
@@ -51,6 +52,56 @@ describe('IssuerClient', () => {
|
||||
expect(JSON.parse(String(init.body))).toEqual({ c: 'v1.x', nonce: '17', v: '5.1.0' });
|
||||
});
|
||||
|
||||
it("SIISS-007: asks and registers at a dialect's own paths, with its own header", async () => {
|
||||
const challenge = { c: 'v1.x', alg: 'scrypt', N: 16_384, r: 8, p: 1, bits: 6, expires_at: 1_793_000_600 };
|
||||
safeFetch.mockResolvedValueOnce(json(challenge));
|
||||
await issuer.challenge('/v1/register/AbCdEfGhIj_-/challenge');
|
||||
expect(lastCall().url).toBe('https://places.liketrek.com/v1/register/AbCdEfGhIj_-/challenge');
|
||||
|
||||
safeFetch.mockResolvedValueOnce(json(GRANT, 201));
|
||||
const request = { body: { passage: { harbor: '2a' } }, headers: { 'X-TREK-Ferry-Seal': 'q1w2e3' } };
|
||||
await issuer.register('/v1/register/AbCdEfGhIj_-', request);
|
||||
const { url, init } = lastCall();
|
||||
expect(url).toBe('https://places.liketrek.com/v1/register/AbCdEfGhIj_-');
|
||||
expect(init.headers['X-TREK-Ferry-Seal']).toBe('q1w2e3');
|
||||
expect(init.headers['Content-Type']).toBe('application/json');
|
||||
expect(init.headers['User-Agent']).toMatch(/^TREK\//);
|
||||
expect(JSON.parse(String(init.body))).toEqual({ passage: { harbor: '2a' } });
|
||||
});
|
||||
|
||||
it.each([
|
||||
['the renewal path', '/v1/register/renew'],
|
||||
['another host', 'https://example.org/v1/register'],
|
||||
['a path past the dialect', '/v1/register/AbCdEfGhIj_-/x'],
|
||||
['an id of the wrong length', '/v1/register/short'],
|
||||
])('SIISS-008: never registers at %s', async (_, path) => {
|
||||
await expect(issuer.register(path, { body: {}, headers: {} })).rejects.toThrow(/registers elsewhere/);
|
||||
expect(safeFetch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('SIISS-009: never asks for a challenge outside the registration paths', async () => {
|
||||
await expect(issuer.challenge('/v1/quota')).rejects.toThrow(/challenge elsewhere/);
|
||||
expect(safeFetch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each([
|
||||
['a header outside X-TREK-', { Authorization: 'Bearer x' }],
|
||||
['a header the gate answers with', { 'X-TREK-Install': 'abc' }],
|
||||
['a quota header', { 'X-TREK-Quota-Remaining': '1' }],
|
||||
['a value with a line break', { 'X-TREK-Ferry-Seal': 'a\r\nb' }],
|
||||
['an empty value', { 'X-TREK-Ferry-Seal': '' }],
|
||||
['a value past 256 characters', { 'X-TREK-Ferry-Seal': 'a'.repeat(257) }],
|
||||
])('SIISS-010: never sends %s', async (_, headers) => {
|
||||
await expect(issuer.register('/v1/register', { body: {}, headers })).rejects.toThrow(/header/);
|
||||
expect(safeFetch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('SIISS-011: never sends a body larger than a registration', async () => {
|
||||
const body = { padding: 'x'.repeat(2048) };
|
||||
await expect(issuer.register('/v1/register', { body, headers: {} })).rejects.toThrow(/larger/);
|
||||
expect(safeFetch).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('SIISS-003: renews and reads the allowance with the key as bearer, the legacy pool without one', async () => {
|
||||
safeFetch.mockResolvedValueOnce(json(GRANT));
|
||||
await issuer.renew('tk1.old.key.sig');
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
/**
|
||||
* The registration dialect: the module this build carries, and the issuer's
|
||||
* sample that uses every building block a generated dialect can be made of.
|
||||
* Each must compute what the issuer computed for its fixed inputs (SELF_CHECK),
|
||||
* and its requests must be ones the issuer client lets out, so a dialect that
|
||||
* reaches main is one TREK can run.
|
||||
*/
|
||||
import { IssuerClient } from '../../../../src/nest/service-identity/issuer.client';
|
||||
import * as committed from '../../../../src/nest/service-identity/registration-dialect';
|
||||
import type {
|
||||
DialectInputs,
|
||||
DialectSelfCheck,
|
||||
RegistrationDialect,
|
||||
} from '../../../../src/nest/service-identity/registration-dialect.types';
|
||||
import { leadingZeroBits, powHash, solvePow } from '../../../../src/nest/service-identity/service-key.pow';
|
||||
import * as sample from '../../../fixtures/service-identity/registration-dialect.sample';
|
||||
|
||||
import { createHash, scryptSync } from 'node:crypto';
|
||||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
const { safeFetch } = vi.hoisted(() => ({ safeFetch: vi.fn() }));
|
||||
vi.mock('../../../../src/utils/ssrfGuard', async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import('../../../../src/utils/ssrfGuard')>()),
|
||||
safeFetch,
|
||||
}));
|
||||
|
||||
beforeEach(() => safeFetch.mockReset());
|
||||
|
||||
const json = (body: unknown, status = 200) =>
|
||||
new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
|
||||
|
||||
const sha256 = (data: Buffer | string) => createHash('sha256').update(data).digest('hex');
|
||||
|
||||
function inputsOf(check: DialectSelfCheck): DialectInputs {
|
||||
return {
|
||||
challenge: check.challenge,
|
||||
version: check.version,
|
||||
random: Buffer.from(check.random, 'hex'),
|
||||
nowSeconds: check.nowSeconds,
|
||||
};
|
||||
}
|
||||
|
||||
const modules: [string, { registrationDialect: RegistrationDialect; SELF_CHECK: DialectSelfCheck }][] = [
|
||||
['the committed dialect', committed],
|
||||
["the issuer's sample", sample],
|
||||
];
|
||||
|
||||
describe.each(modules)('%s', (_, { registrationDialect: dialect, SELF_CHECK: check }) => {
|
||||
it('SIDIA-001: computes the password, salt and proof of work the issuer computed', () => {
|
||||
const { password, salt } = dialect.begin(inputsOf(check)).work(check.nonce);
|
||||
expect(sha256(password)).toBe(check.passwordSha256);
|
||||
expect(sha256(salt)).toBe(check.saltSha256);
|
||||
const { N, r, p } = check.challenge;
|
||||
expect(scryptSync(password, salt, 32, { N, r, p }).toString('hex')).toBe(check.scrypt);
|
||||
});
|
||||
|
||||
it('SIDIA-002: sends the request the issuer expects', () => {
|
||||
const { body, headers } = dialect.begin(inputsOf(check)).request(check.nonce);
|
||||
expect(sha256(JSON.stringify({ body, headers }))).toBe(check.requestSha256);
|
||||
});
|
||||
|
||||
it('SIDIA-003: gives the same answer for the same inputs, whenever it is asked', () => {
|
||||
const first = dialect.begin(inputsOf(check));
|
||||
const second = dialect.begin(inputsOf(check));
|
||||
expect(second.work(check.nonce)).toEqual(first.work(check.nonce));
|
||||
expect(second.request(check.nonce)).toEqual(first.request(check.nonce));
|
||||
expect(first.work(check.nonce + 1).password).not.toEqual(first.work(check.nonce).password);
|
||||
});
|
||||
|
||||
it('SIDIA-004: names itself as the issuer and the release job expect', () => {
|
||||
expect(dialect.id).toMatch(/^(0|[A-Za-z0-9_-]{12})$/);
|
||||
expect(dialect.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
|
||||
expect(Number.isNaN(Date.parse(dialect.createdAt))).toBe(false);
|
||||
expect(dialect.releasedFor).toMatch(/^(dev|\d+\.\d+\.\d+(-pre\.\d+)?)$/);
|
||||
});
|
||||
|
||||
it('SIDIA-005: its challenge and registration go out through the issuer client', async () => {
|
||||
const challenge = { ...check.challenge, expires_at: 1_900_000_000 };
|
||||
safeFetch.mockResolvedValueOnce(json(challenge));
|
||||
const issuer = new IssuerClient();
|
||||
await issuer.challenge(dialect.challengePath);
|
||||
expect(safeFetch.mock.calls.at(-1)?.[0]).toBe(`https://places.liketrek.com${dialect.challengePath}`);
|
||||
|
||||
const grant = { key: 'tk1.a.b.c', exp: 1_800_776_000, renew_after: 1_798_184_000 };
|
||||
safeFetch.mockResolvedValueOnce(json(grant, 201));
|
||||
const request = dialect.begin(inputsOf(check)).request(2 ** 40);
|
||||
await expect(issuer.register(dialect.registerPath, request)).resolves.toMatchObject({ body: grant });
|
||||
const [url, init] = safeFetch.mock.calls.at(-1) ?? [];
|
||||
expect(url).toBe(`https://places.liketrek.com${dialect.registerPath}`);
|
||||
expect(JSON.parse(String(init.body))).toEqual(request.body);
|
||||
for (const [name, value] of Object.entries(request.headers)) expect(init.headers[name]).toBe(value);
|
||||
});
|
||||
|
||||
it('SIDIA-006: a proof of work can be found in it', async () => {
|
||||
const challenge = { ...check.challenge, bits: 4 };
|
||||
const attempt = dialect.begin(inputsOf({ ...check, challenge }));
|
||||
const nonce = await solvePow(challenge, attempt, Date.now() + 60_000);
|
||||
expect(leadingZeroBits(await powHash(attempt.work(nonce), challenge))).toBeGreaterThanOrEqual(4);
|
||||
});
|
||||
});
|
||||
@@ -14,7 +14,7 @@ interface Vector {
|
||||
name: string;
|
||||
token: string;
|
||||
valid: boolean;
|
||||
payload?: { i: string; iat: number; exp: number; q: string };
|
||||
payload?: { i: string; iat: number; exp: number; q: string; d?: string };
|
||||
payload_json?: string;
|
||||
}
|
||||
|
||||
@@ -44,7 +44,10 @@ describe('parseServiceKey against the shared vectors', () => {
|
||||
const key = parseServiceKey(vector.token);
|
||||
expect(key).not.toBeNull();
|
||||
expect(key?.kid).toBe(fixture.kid);
|
||||
expect(key?.payload).toEqual(vector.payload);
|
||||
// The dialect a key was registered in is the issuer's statistic; TREK has no use for it.
|
||||
const payload: NonNullable<Vector['payload']> = vector.payload ?? { i: '', iat: 0, exp: 0, q: '' };
|
||||
const { d: _dialect, ...read } = payload;
|
||||
expect(key?.payload).toEqual(read);
|
||||
const body = vector.token.split('.')[2];
|
||||
expect(Buffer.from(body, 'base64url').toString('utf8')).toBe(vector.payload_json);
|
||||
},
|
||||
@@ -68,6 +71,17 @@ describe('parseServiceKey against the shared vectors', () => {
|
||||
const tampered = invalid.find((v) => v.name === 'tampered_payload')?.token ?? '';
|
||||
expect(parseServiceKey(tampered)?.payload.q).toBe('own');
|
||||
});
|
||||
|
||||
it('SIKEY-005: reads a key that names the dialect it was registered in like any other', () => {
|
||||
const vector = valid.find((v) => v.name === 'std_with_dialect');
|
||||
expect(vector?.payload?.d).toBeDefined();
|
||||
expect(parseServiceKey(vector?.token ?? '')?.payload).toEqual({
|
||||
i: vector?.payload?.i,
|
||||
iat: vector?.payload?.iat,
|
||||
exp: vector?.payload?.exp,
|
||||
q: 'std',
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe('parseServiceKey on anything else', () => {
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
/**
|
||||
* The registration proof of work, against the vector the issuer checks with:
|
||||
* scrypt(c + "." + nonce, "trek-pow-v1", N, r, p, 32 bytes), at least `bits`
|
||||
* leading zero bits.
|
||||
* scrypt over what the dialect makes of a nonce (in the original registration
|
||||
* c + "." + nonce with the salt "trek-pow-v1"), N, r, p, 32 bytes, at least
|
||||
* `bits` leading zero bits.
|
||||
*/
|
||||
import type { DialectAttempt } from '../../../../src/nest/service-identity/registration-dialect.types';
|
||||
import { leadingZeroBits, powHash, solvePow } from '../../../../src/nest/service-identity/service-key.pow';
|
||||
import type { ServiceChallenge } from '@trek/shared';
|
||||
|
||||
@@ -25,15 +27,26 @@ const { pow } = JSON.parse(
|
||||
};
|
||||
};
|
||||
|
||||
/** The original registration's work: the challenge, a dot and the decimal nonce, salted as in its first version. */
|
||||
const original = (c: string, nonce: number | string) => ({
|
||||
password: Buffer.from(`${c}.${nonce}`, 'utf8'),
|
||||
salt: Buffer.from('trek-pow-v1', 'utf8'),
|
||||
});
|
||||
|
||||
const attemptFor = (c: string): DialectAttempt => ({
|
||||
work: (nonce) => original(c, nonce),
|
||||
request: () => ({ body: {}, headers: {} }),
|
||||
});
|
||||
|
||||
describe('powHash against the shared vector', () => {
|
||||
it('SIPOW-001: hashes the valid nonce to the published hash, which meets the target', async () => {
|
||||
const hash = await powHash(pow.c, pow.valid_nonce, pow);
|
||||
const hash = await powHash(original(pow.c, pow.valid_nonce), pow);
|
||||
expect(hash.toString('hex')).toBe(pow.hash_hex);
|
||||
expect(leadingZeroBits(hash)).toBeGreaterThanOrEqual(pow.bits);
|
||||
});
|
||||
|
||||
it('SIPOW-002: the next nonce misses the target', async () => {
|
||||
expect(leadingZeroBits(await powHash(pow.c, pow.invalid_nonce, pow))).toBeLessThan(pow.bits);
|
||||
expect(leadingZeroBits(await powHash(original(pow.c, pow.invalid_nonce), pow))).toBeLessThan(pow.bits);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -52,16 +65,16 @@ describe('solvePow', () => {
|
||||
const cheap: ServiceChallenge = { c: 'v1.cheap', alg: 'scrypt', N: 16, r: 1, p: 1, bits: 4, expires_at: 1 };
|
||||
|
||||
it('SIPOW-020: finds the first nonce that meets the target, at low difficulty', async () => {
|
||||
const nonce = await solvePow(cheap, Date.now() + 60_000);
|
||||
expect(nonce).toMatch(/^\d+$/);
|
||||
expect(leadingZeroBits(await powHash(cheap.c, nonce, cheap))).toBeGreaterThanOrEqual(cheap.bits);
|
||||
const earlier = Array.from({ length: Number(nonce) }, (_, n) => powHash(cheap.c, String(n), cheap));
|
||||
const nonce = await solvePow(cheap, attemptFor(cheap.c), Date.now() + 60_000);
|
||||
expect(Number.isInteger(nonce)).toBe(true);
|
||||
expect(leadingZeroBits(await powHash(original(cheap.c, nonce), cheap))).toBeGreaterThanOrEqual(cheap.bits);
|
||||
const earlier = Array.from({ length: nonce }, (_, n) => powHash(original(cheap.c, n), cheap));
|
||||
for (const hash of await Promise.all(earlier)) {
|
||||
expect(leadingZeroBits(hash)).toBeLessThan(cheap.bits);
|
||||
}
|
||||
});
|
||||
|
||||
it('SIPOW-021: gives up once the challenge has expired', async () => {
|
||||
await expect(solvePow({ ...cheap, bits: 24 }, Date.now() - 1)).rejects.toThrow(/expired/);
|
||||
await expect(solvePow({ ...cheap, bits: 24 }, attemptFor(cheap.c), Date.now() - 1)).rejects.toThrow(/expired/);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -9,7 +9,12 @@ import { RuntimeEnvService } from '../../../../src/nest/app-config/runtime-env.s
|
||||
import { servicesConfig } from '../../../../src/nest/app-config/tokens';
|
||||
import { DomainError } from '../../../../src/nest/common/domain-error';
|
||||
import { IssuerClient, IssuerError } from '../../../../src/nest/service-identity/issuer.client';
|
||||
import type {
|
||||
DialectInputs,
|
||||
RegistrationDialect,
|
||||
} from '../../../../src/nest/service-identity/registration-dialect.types';
|
||||
import { ServiceClock } from '../../../../src/nest/service-identity/service-clock';
|
||||
import { REGISTRATION_DIALECT } from '../../../../src/nest/service-identity/service-identity.constants';
|
||||
import { keyFingerprint } from '../../../../src/nest/service-identity/service-identity.helpers';
|
||||
import { ServiceKeyService } from '../../../../src/nest/service-identity/service-key.service';
|
||||
import {
|
||||
@@ -25,6 +30,12 @@ import { createTestModule, type TestModule } from '../../../helpers/test-module'
|
||||
|
||||
import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
const { logWarn } = vi.hoisted(() => ({ logWarn: vi.fn() }));
|
||||
vi.mock('../../../../src/nest/audit/audit-log.logger', async (importOriginal) => ({
|
||||
...(await importOriginal<typeof import('../../../../src/nest/audit/audit-log.logger')>()),
|
||||
logWarn,
|
||||
}));
|
||||
|
||||
const DAY = 86_400;
|
||||
const now = () => Math.floor(Date.now() / 1000);
|
||||
|
||||
@@ -81,6 +92,23 @@ function fakeIssuer(issued = KEY) {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The original registration, pinned here rather than read from the committed
|
||||
* dialect, which every release replaces; registration-dialect.test.ts holds
|
||||
* whatever the committed one is to the issuer's own computation.
|
||||
*/
|
||||
const DIALECT_ZERO: RegistrationDialect = {
|
||||
id: '0',
|
||||
releasedFor: 'dev',
|
||||
createdAt: '2026-10-29',
|
||||
challengePath: '/v1/register/challenge',
|
||||
registerPath: '/v1/register',
|
||||
begin: ({ challenge, version }) => ({
|
||||
work: (nonce) => ({ password: Buffer.from(`${challenge.c}.${nonce}`), salt: Buffer.from('trek-pow-v1') }),
|
||||
request: (nonce) => ({ body: { c: challenge.c, nonce: String(nonce), v: version }, headers: {} }),
|
||||
}),
|
||||
};
|
||||
|
||||
const testDb = createSnapshotTestDb();
|
||||
let t: TestModule | null = null;
|
||||
|
||||
@@ -90,6 +118,7 @@ interface Setup {
|
||||
isTest?: boolean;
|
||||
store?: ReturnType<typeof fakeStore>;
|
||||
issuer?: ReturnType<typeof fakeIssuer>;
|
||||
dialect?: RegistrationDialect;
|
||||
}
|
||||
|
||||
async function build(setup: Setup = {}) {
|
||||
@@ -107,6 +136,7 @@ async function build(setup: Setup = {}) {
|
||||
{ provide: IssuerClient, useValue: issuer },
|
||||
{ provide: servicesConfig.KEY, useValue: config },
|
||||
{ provide: RuntimeEnvService, useValue: { env: () => ({ maps }), isTest: () => setup.isTest ?? false } },
|
||||
{ provide: REGISTRATION_DIALECT, useValue: setup.dialect ?? DIALECT_ZERO },
|
||||
],
|
||||
});
|
||||
return { keys: t.get(ServiceKeyService), store, issuer };
|
||||
@@ -117,6 +147,7 @@ const settled = (keys: ServiceKeyService) => keys.whenIdle();
|
||||
|
||||
afterEach(async () => {
|
||||
vi.useRealTimers();
|
||||
logWarn.mockClear();
|
||||
await t?.close();
|
||||
t = null;
|
||||
});
|
||||
@@ -128,7 +159,11 @@ describe('registration', () => {
|
||||
const { keys, store, issuer } = await build();
|
||||
expect(keys.bearer()).toBeNull();
|
||||
await settled(keys);
|
||||
expect(issuer.register).toHaveBeenCalledWith({ c: 'v1.challenge', nonce: '0', v: runningVersion() });
|
||||
expect(issuer.challenge).toHaveBeenCalledWith('/v1/register/challenge');
|
||||
expect(issuer.register).toHaveBeenCalledWith('/v1/register', {
|
||||
body: { c: 'v1.challenge', nonce: '0', v: runningVersion().slice(0, 32) },
|
||||
headers: {},
|
||||
});
|
||||
expect(store.claim).toHaveBeenCalledTimes(1);
|
||||
expect(store.current().state.renewAfter).toBeGreaterThan(now());
|
||||
expect(keys.bearer()).toBe(KEY);
|
||||
@@ -210,6 +245,92 @@ describe('registration', () => {
|
||||
await settled(again.keys);
|
||||
expect(refusing.challenge).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('SIKEYS-008: a release whose dialect the issuer no longer takes waits a day, says so once, and is not retried', async () => {
|
||||
vi.useFakeTimers({ toFake: ['Date'] });
|
||||
const issuer = fakeIssuer();
|
||||
issuer.challenge.mockRejectedValue(new IssuerError(410, null, null));
|
||||
const { keys, store } = await build({ issuer });
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(1);
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(1);
|
||||
|
||||
vi.setSystemTime(Date.now() + 23 * 3_600_000);
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(1);
|
||||
vi.setSystemTime(Date.now() + 2 * 3_600_000);
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(2);
|
||||
|
||||
const lines = logWarn.mock.calls.map(([line]) => String(line));
|
||||
expect(lines).toHaveLength(1);
|
||||
expect(lines[0]).toMatch(/can no longer register/);
|
||||
expect(store.claim).not.toHaveBeenCalled();
|
||||
expect(keys.bearer()).toBeNull();
|
||||
expect((await keys.snapshot()).state).toBe('legacy');
|
||||
});
|
||||
|
||||
it('SIKEYS-015: the wait after a refused dialect follows the issuer when it names one', async () => {
|
||||
vi.useFakeTimers({ toFake: ['Date'] });
|
||||
const issuer = fakeIssuer();
|
||||
issuer.register.mockRejectedValueOnce(new IssuerError(410, 3_600_000, null));
|
||||
const { keys } = await build({ issuer });
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(1);
|
||||
vi.setSystemTime(Date.now() + 3_601_000);
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledTimes(2);
|
||||
expect(keys.bearer()).toBe(KEY);
|
||||
});
|
||||
|
||||
it('SIKEYS-009: the dialect decides where to ask, what to send and over what the work runs', async () => {
|
||||
const seen: DialectInputs[] = [];
|
||||
const worked: number[] = [];
|
||||
const dialect: RegistrationDialect = {
|
||||
id: 'AbCdEfGhIjKl',
|
||||
releasedFor: '9.9.9',
|
||||
createdAt: '2026-11-01',
|
||||
challengePath: '/v1/register/AbCdEfGhIjKl/challenge',
|
||||
registerPath: '/v1/register/AbCdEfGhIjKl',
|
||||
begin(inputs) {
|
||||
seen.push(inputs);
|
||||
return {
|
||||
work(nonce) {
|
||||
worked.push(nonce);
|
||||
return { password: Buffer.from(`work-${nonce}`), salt: Buffer.from('salt') };
|
||||
},
|
||||
request: (nonce) => ({ body: { harbor: nonce.toString(16) }, headers: { 'X-TREK-Ferry-Seal': 'abc' } }),
|
||||
};
|
||||
},
|
||||
};
|
||||
// The issuer's clock runs five days ahead of this server's; the dialect gets the issuer's time.
|
||||
const issuer = fakeIssuer();
|
||||
issuer.challenge.mockResolvedValueOnce({
|
||||
body: { c: 'v1.challenge', alg: 'scrypt', N: 2, r: 1, p: 1, bits: 0, expires_at: now() + 5 * DAY + 600 },
|
||||
serverMs: Date.now() + 5 * DAY * 1000,
|
||||
});
|
||||
const { keys } = await build({ dialect, issuer });
|
||||
keys.bearer();
|
||||
await settled(keys);
|
||||
expect(issuer.challenge).toHaveBeenCalledWith('/v1/register/AbCdEfGhIjKl/challenge');
|
||||
expect(issuer.register).toHaveBeenCalledWith('/v1/register/AbCdEfGhIjKl', {
|
||||
body: { harbor: '0' },
|
||||
headers: { 'X-TREK-Ferry-Seal': 'abc' },
|
||||
});
|
||||
expect(worked).toEqual([0]);
|
||||
expect(seen).toHaveLength(1);
|
||||
expect(seen[0].challenge.c).toBe('v1.challenge');
|
||||
expect(seen[0].version).toBe(runningVersion().slice(0, 32));
|
||||
expect(seen[0].random).toHaveLength(16);
|
||||
expect(Math.abs(seen[0].nowSeconds - (now() + 5 * DAY))).toBeLessThanOrEqual(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('when it never registers', () => {
|
||||
@@ -413,13 +534,13 @@ describe('renewal', () => {
|
||||
expect(third.store.current().key?.token).toBe(oldKey);
|
||||
});
|
||||
|
||||
it('SIKEYS-034: a key past its 30 days of grace registers anew instead', async () => {
|
||||
const lapsed = serviceKeyTokenFor({ i: 'installation-a', iat: now() - 130 * DAY, exp: now() - 40 * DAY });
|
||||
it('SIKEYS-034: a key past its year of grace registers anew instead', async () => {
|
||||
const lapsed = serviceKeyTokenFor({ i: 'installation-a', iat: now() - 456 * DAY, exp: now() - 366 * DAY });
|
||||
const store = fakeStore({
|
||||
key: {
|
||||
token: lapsed,
|
||||
kid: 'test',
|
||||
payload: { i: 'installation-a', iat: now() - 130 * DAY, exp: now() - 40 * DAY, q: 'std' },
|
||||
payload: { i: 'installation-a', iat: now() - 456 * DAY, exp: now() - 366 * DAY, q: 'std' },
|
||||
},
|
||||
});
|
||||
const { keys, issuer } = await build({ store });
|
||||
@@ -447,22 +568,23 @@ describe('renewal', () => {
|
||||
expect(keys.bearer()).toBe(RENEWED_KEY);
|
||||
});
|
||||
|
||||
it('SIKEYS-037: an expired key within its grace stays home, and the next request renews it', async () => {
|
||||
const expired = serviceKeyTokenFor({ i: 'installation-a', iat: now() - 95 * DAY, exp: now() - 5 * DAY });
|
||||
const store = fakeStore({
|
||||
key: {
|
||||
token: expired,
|
||||
kid: 'test',
|
||||
payload: { i: 'installation-a', iat: now() - 95 * DAY, exp: now() - 5 * DAY, q: 'std' },
|
||||
},
|
||||
});
|
||||
const { keys, issuer } = await build({ store });
|
||||
expect(keys.bearer()).toBeNull();
|
||||
await settled(keys);
|
||||
expect(issuer.renew).toHaveBeenCalledWith(expired);
|
||||
expect(issuer.register).not.toHaveBeenCalled();
|
||||
expect(keys.bearer()).toBe(RENEWED_KEY);
|
||||
});
|
||||
it.each([5, 300])(
|
||||
'SIKEYS-037: a key that expired %i days ago is within its grace, stays home, and the next request renews it',
|
||||
async (daysAgo) => {
|
||||
const iat = now() - (90 + daysAgo) * DAY;
|
||||
const exp = now() - daysAgo * DAY;
|
||||
const expired = serviceKeyTokenFor({ i: 'installation-a', iat, exp });
|
||||
const store = fakeStore({
|
||||
key: { token: expired, kid: 'test', payload: { i: 'installation-a', iat, exp, q: 'std' } },
|
||||
});
|
||||
const { keys, issuer } = await build({ store });
|
||||
expect(keys.bearer()).toBeNull();
|
||||
await settled(keys);
|
||||
expect(issuer.renew).toHaveBeenCalledWith(expired);
|
||||
expect(issuer.register).not.toHaveBeenCalled();
|
||||
expect(keys.bearer()).toBe(RENEWED_KEY);
|
||||
},
|
||||
);
|
||||
|
||||
it('SIKEYS-038: after a failed renewal the requests wait for the backoff instead of asking again', async () => {
|
||||
vi.useFakeTimers({ toFake: ['Date'] });
|
||||
|
||||
Reference in New Issue
Block a user