diff --git a/server/.prettierignore b/server/.prettierignore index 530a8ab95..0d73c8cde 100644 --- a/server/.prettierignore +++ b/server/.prettierignore @@ -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 diff --git a/server/scripts/format-lint.mjs b/server/scripts/format-lint.mjs index ddf9aebc0..72685dec2 100644 --- a/server/scripts/format-lint.mjs +++ b/server/scripts/format-lint.mjs @@ -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 . 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'), }), diff --git a/server/src/nest/service-identity/issuer.client.ts b/server/src/nest/service-identity/issuer.client.ts index 8999de357..1265caaa4 100644 --- a/server/src/nest/service-identity/issuer.client.ts +++ b/server/src/nest/service-identity/issuer.client.ts @@ -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 { 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> { - 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> { + 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> { - return this.call('POST', '/v1/register', serviceKeyGrantSchema, { body: request }); + register(path: string, request: RegistrationRequest): Promise> { + 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> { @@ -69,9 +85,18 @@ export class IssuerClient { method: 'GET' | 'POST', path: string, schema: z.ZodType, - opts: { body?: RegistrationRequest; bearer?: string | null; origin?: string } = {}, + opts: { + body?: Record; + headers?: Record; + bearer?: string | null; + origin?: string; + } = {}, ): Promise> { - const headers: Record = { Accept: 'application/json', 'User-Agent': serviceUserAgent() }; + const headers: Record = { + ...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); +} diff --git a/server/src/nest/service-identity/registration-dialect.ts b/server/src/nest/service-identity/registration-dialect.ts new file mode 100644 index 000000000..8a40a133c --- /dev/null +++ b/server/src/nest/service-identity/registration-dialect.ts @@ -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', +}; diff --git a/server/src/nest/service-identity/registration-dialect.types.ts b/server/src/nest/service-identity/registration-dialect.types.ts new file mode 100644 index 000000000..6df16f8f8 --- /dev/null +++ b/server/src/nest/service-identity/registration-dialect.types.ts @@ -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; + headers: Record; +} + +/** 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; +} diff --git a/server/src/nest/service-identity/service-identity.constants.ts b/server/src/nest/service-identity/service-identity.constants.ts index 97ebd17d3..167274cbd 100644 --- a/server/src/nest/service-identity/service-identity.constants.ts +++ b/server/src/nest/service-identity/service-identity.constants.ts @@ -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'); diff --git a/server/src/nest/service-identity/service-identity.module.ts b/server/src/nest/service-identity/service-identity.module.ts index 8c73e52a2..fbcd990dc 100644 --- a/server/src/nest/service-identity/service-identity.module.ts +++ b/server/src/nest/service-identity/service-identity.module.ts @@ -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], }) diff --git a/server/src/nest/service-identity/service-key.pow.ts b/server/src/nest/service-identity/service-key.pow.ts index b24c9680d..469dcab5e 100644 --- a/server/src/nest/service-identity/service-key.pow.ts +++ b/server/src/nest/service-identity/service-key.pow.ts @@ -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; -/** scrypt(c + "." + nonce, "trek-pow-v1"), off the event loop. */ -export function powHash(challenge: string, nonce: string, cost: ScryptCost): Promise { +/** scrypt over what the dialect made of one nonce, off the event loop. */ +export function powHash(input: ProofInput, cost: ScryptCost): Promise { 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 { - 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 { + return firstNonceFrom(0, challenge, attempt, deadlineMs); } -async function firstNonceFrom(nonce: number, challenge: ServiceChallenge, deadlineMs: number): Promise { +async function firstNonceFrom( + nonce: number, + challenge: ServiceChallenge, + attempt: DialectAttempt, + deadlineMs: number, +): Promise { 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); } diff --git a/server/src/nest/service-identity/service-key.service.ts b/server/src/nest/service-identity/service-key.service.ts index ba45ff54e..6c3aa9a8a 100644 --- a/server/src/nest/service-identity/service-key.service.ts +++ b/server/src/nest/service-identity/service-key.service.ts @@ -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> { - 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. */ diff --git a/server/tests/fixtures/service-identity/registration-dialect.sample.ts b/server/tests/fixtures/service-identity/registration-dialect.sample.ts new file mode 100644 index 000000000..2d236f0d3 --- /dev/null +++ b/server/tests/fixtures/service-identity/registration-dialect.sample.ts @@ -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', +}; diff --git a/server/tests/fixtures/service-identity/registration-dialect.types.ts b/server/tests/fixtures/service-identity/registration-dialect.types.ts new file mode 100644 index 000000000..02ffbaa09 --- /dev/null +++ b/server/tests/fixtures/service-identity/registration-dialect.types.ts @@ -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'; diff --git a/server/tests/fixtures/service-identity/tk1-vectors.json b/server/tests/fixtures/service-identity/tk1-vectors.json index 9ed76c093..2b5b4c3c7 100644 --- a/server/tests/fixtures/service-identity/tk1-vectors.json +++ b/server/tests/fixtures/service-identity/tk1-vectors.json @@ -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", diff --git a/server/tests/unit/nest/service-identity/issuer.client.test.ts b/server/tests/unit/nest/service-identity/issuer.client.test.ts index 6e4a880a0..3ca6acf0d 100644 --- a/server/tests/unit/nest/service-identity/issuer.client.test.ts +++ b/server/tests/unit/nest/service-identity/issuer.client.test.ts @@ -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'); diff --git a/server/tests/unit/nest/service-identity/registration-dialect.test.ts b/server/tests/unit/nest/service-identity/registration-dialect.test.ts new file mode 100644 index 000000000..371c65666 --- /dev/null +++ b/server/tests/unit/nest/service-identity/registration-dialect.test.ts @@ -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()), + 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); + }); +}); diff --git a/server/tests/unit/nest/service-identity/service-key.format.test.ts b/server/tests/unit/nest/service-identity/service-key.format.test.ts index dcee67a25..76d683e7e 100644 --- a/server/tests/unit/nest/service-identity/service-key.format.test.ts +++ b/server/tests/unit/nest/service-identity/service-key.format.test.ts @@ -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 ?? { 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', () => { diff --git a/server/tests/unit/nest/service-identity/service-key.pow.test.ts b/server/tests/unit/nest/service-identity/service-key.pow.test.ts index ab3e8f009..bac4c722a 100644 --- a/server/tests/unit/nest/service-identity/service-key.pow.test.ts +++ b/server/tests/unit/nest/service-identity/service-key.pow.test.ts @@ -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/); }); }); diff --git a/server/tests/unit/nest/service-identity/service-key.service.test.ts b/server/tests/unit/nest/service-identity/service-key.service.test.ts index 91cc4e553..f14d181e0 100644 --- a/server/tests/unit/nest/service-identity/service-key.service.test.ts +++ b/server/tests/unit/nest/service-identity/service-key.service.test.ts @@ -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()), + 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; issuer?: ReturnType; + 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'] });