@oxy.so/core 1.5.1 → 1.6.1

package/dist/types/server/securityHeaders.d.ts

@@ -155,6 +155,14 @@ export declare function inlineScriptCspHash(source: string): string;
 export interface OxyPagesHeadersOptions {
     /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
     csp?: OxyCspExtensions;
+    /**
+     * An origin where people authenticate, consent or recover (`auth.oxy.so`,
+     * ADR 0024 D1). The Cloudflare Insights beacon — injected by the edge, not by
+     * the app — is REMOVED from `script-src` and `connect-src`, so third-party
+     * measurement cannot run there even when the zone has Web Analytics enabled.
+     * A structural block in the policy the page is served with, not a build flag.
+     */
+    sensitive?: boolean;
     /**
      * Emit `Strict-Transport-Security` (default `true`). Cloudflare Pages serves
      * HTTPS only, so static deploys should keep this on.

package/dist/types/server/workloadIdentity.d.ts

@@ -0,0 +1,32 @@
+export interface WorkloadServiceTokenOptions {
+    /** Oxy's base URL, e.g. `https://api.oxy.so`. */
+    baseUrl: string;
+    /** Injected in tests; defaults to the global. */
+    fetch?: typeof fetch;
+}
+export interface WorkloadServiceToken {
+    token: string;
+    /** Seconds from now, as Oxy reported it. */
+    expiresIn: number;
+    appName: string;
+}
+/**
+ * Whether this process can attest at all.
+ *
+ * The relative URI is set by ECS on every task and by nothing else, so its
+ * presence is the honest test for "we can prove what we are here". A local
+ * checkout has no attestation to offer and must fall back to a credential.
+ */
+export declare function canAttestWorkloadIdentity(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Exchanges this process's identity for an Oxy service token.
+ *
+ * Two round trips by design (see ADR 0026): a nonce, then an attestation that
+ * signs it. The caller caches the token — it lives an hour — rather than doing
+ * this per request.
+ *
+ * Failures are thrown, never swallowed into an empty token: a caller that
+ * cannot prove what it is must not go on to make an unauthenticated request and
+ * discover the problem as a 401 somewhere else.
+ */
+export declare function requestWorkloadServiceToken(options: WorkloadServiceTokenOptions): Promise<WorkloadServiceToken>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,7 +118,7 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.2.0",
+    "@oxy.so/contracts": "^1.3.0",
     "@oxy.so/protocol": "^1.0.1",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",

package/src/HttpService.ts

@@ -186,6 +186,34 @@ const TOKEN_REFRESH_COOLDOWN_MS = 15000;
  */
 const EXPIRED_TOKEN_REFRESH_COOLDOWN_MS = 1000;
 
+/**
+ * Cooldown (ms) applied after the refresh endpoint answered 429 Too Many
+ * Requests. Overrides BOTH cooldowns above, because neither of them is about
+ * this failure.
+ *
+ * The other two ask "is the current token still usable?" and answer a server
+ * that is unreachable or erroring. A 429 is the opposite situation: the server
+ * is perfectly reachable and is telling this client, specifically, that it is
+ * asking too often. `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS` then becomes actively
+ * harmful — an expired token drives the request-time preflight and the 401
+ * retry lanes at one mint per second (60/min) against a mint budget of 30/min,
+ * so the client's own retries hold the limiter tripped and it can never fall
+ * back under the ceiling. The limit stops being self-clearing and becomes
+ * self-sustaining for as long as the app keeps issuing requests.
+ *
+ * Sized to the mint limiter's own window (60s, `packages/api/src/routes/sessionDevice.ts`)
+ * so ONE attempt lands per window: enough to discover the moment the budget has
+ * drained, never enough to consume it. The per-device lockout answers 429 for
+ * far longer (15 min), and that is fine — one probe a minute against it is
+ * negligible traffic and the session recovers the instant the lockout lifts.
+ *
+ * NOT routed through the scheduler's exponential backoff: that backoff is
+ * effect-local to `startTokenRefreshScheduler` and governs only the scheduled
+ * lane, while the lanes that actually produce the storm here (preflight, 401
+ * retry) are request-driven and are throttled solely by this cooldown.
+ */
+const RATE_LIMITED_REFRESH_COOLDOWN_MS = 60_000;
+
 /**
  * Lead time (seconds) before access-token expiry at which a preflight refresh
  * is triggered. A token within this window of `exp` is treated as effectively
@@ -293,6 +321,17 @@ export class HttpService {
    * fixed deadline that could not shrink once the token expired mid-cooldown.
    */
   private lastRefreshFailureAt = 0;
+  /**
+   * Whether the last refresh failure was the server answering 429. Selects
+   * {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} over the two token-state cooldowns
+   * for the NEXT attempt, and is cleared by any success or any other failure.
+   *
+   * A boolean beside {@link lastRefreshFailureAt} rather than a stored deadline,
+   * for the same reason that field gives: the cooldown stays a function of the
+   * current state, so it can still shorten if the situation changes underneath
+   * it, and there is exactly one timestamp to reason about.
+   */
+  private lastRefreshWasRateLimited = false;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
@@ -1156,20 +1195,29 @@ export class HttpService {
       return null;
     }
 
-    // Post-failure cooldown. A genuinely EXPIRED current token uses a much
-    // shorter cooldown than a still-valid (proactive, near-expiry) one: an
-    // expired token is unusable, so re-mint as soon as the endpoint is reachable
-    // again rather than waiting out the full window while requests carry a stale
-    // bearer. Both cooldowns are measured from the last failure, so the moment a
-    // still-valid token crosses `exp` mid-cooldown the shorter window applies.
-    const cooldownMs = this.isAccessTokenExpired()
-      ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
-      : TOKEN_REFRESH_COOLDOWN_MS;
+    // Post-failure cooldown. A 429 names its own window regardless of token
+    // state — the server is reachable and is rationing this client, so retrying
+    // at the expired-token rate would spend the very budget being waited on.
+    // Otherwise a genuinely EXPIRED current token uses a much shorter cooldown
+    // than a still-valid (proactive, near-expiry) one: an expired token is
+    // unusable, so re-mint as soon as the endpoint is reachable again rather
+    // than waiting out the full window while requests carry a stale bearer. All
+    // three are measured from the last failure, so the moment a still-valid
+    // token crosses `exp` mid-cooldown the shorter window applies.
+    const cooldownMs = this.lastRefreshWasRateLimited
+      ? RATE_LIMITED_REFRESH_COOLDOWN_MS
+      : this.isAccessTokenExpired()
+        ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
+        : TOKEN_REFRESH_COOLDOWN_MS;
     if (Date.now() - this.lastRefreshFailureAt < cooldownMs) {
       return null;
     }
 
     if (!this.tokenRefreshPromise) {
+      // Cleared before the attempt, never after it: the handler reports a 429
+      // by calling `noteRefreshRateLimited()` from INSIDE this call, so clearing
+      // on the way out would discard the flag it just set.
+      this.lastRefreshWasRateLimited = false;
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (!newToken) {
@@ -1183,6 +1231,7 @@ export class HttpService {
           // A success clears the failure timestamp so the next refresh is never
           // throttled by a stale cooldown.
           this.lastRefreshFailureAt = 0;
+          this.lastRefreshWasRateLimited = false;
           this.logger.debug('Token refreshed via the auth refresh handler');
           return newToken;
         })
@@ -1199,6 +1248,22 @@ export class HttpService {
     return this.tokenRefreshPromise;
   }
 
+  /**
+   * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
+   * next attempt waits {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} instead of one of
+   * the token-state cooldowns.
+   *
+   * Called by the refresh handler (`refreshDeviceSecretArm`) from inside the
+   * `authRefreshHandler` call, because the handler's `Promise<string | null>`
+   * contract cannot carry WHY a refresh failed and 429 is the one failure whose
+   * correct retry interval is set by the server rather than by the token.
+   *
+   * Public because the handler lives in `session/refresh.ts`, not on this class.
+   */
+  noteRefreshRateLimited(): void {
+    this.lastRefreshWasRateLimited = true;
+  }
+
   /**
    * Whether the CURRENT stored access token is already past its `exp`. Drives
    * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):

package/src/__tests__/httpServiceRateLimitedRefresh.test.ts

@@ -0,0 +1,160 @@
+/**
+ * The post-429 refresh cooldown.
+ *
+ * `POST /session/device/token` is budgeted at 30 mints/minute
+ * (`packages/api/src/routes/sessionDevice.ts`). Once the access token is
+ * EXPIRED, the request-driven refresh lanes — the request-time preflight in
+ * `getAuthHeader` and the 401 retry — reattempt on
+ * `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS`, i.e. one mint per second, 60/min. That
+ * is correct against an unreachable server (recover the instant it returns) and
+ * exactly wrong against a rationing one: the retries spend the very budget they
+ * are waiting on, so the limiter stays tripped for as long as the app keeps
+ * issuing requests and the session can never heal itself.
+ *
+ * These tests pin the discrimination: a 429 lengthens the NEXT cooldown to the
+ * limiter's own window, every other failure keeps the token-state cooldowns, and
+ * a success clears it.
+ *
+ * `Date.now` is stubbed rather than using fake timers: the cooldown is a pure
+ * comparison against a stored epoch, so moving the clock is the whole
+ * experiment, and real microtasks keep the refresh promises resolving normally.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+/** The server's mint budget window — the interval the fix must wait out. */
+const LIMITER_WINDOW_MS = 60_000;
+
+/** Comfortably past the expired-token cooldown (1s) but inside the 429 window. */
+const BETWEEN_COOLDOWNS_MS = 30_000;
+
+describe('HttpService — refresh cooldown after a rate-limited mint', () => {
+  let clock = 1_700_000_000_000;
+
+  beforeEach(() => {
+    clock = 1_700_000_000_000;
+    jest.spyOn(Date, 'now').mockImplementation(() => clock);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /** A client whose CURRENT access token is already past `exp`. */
+  function expiredTokenClient(): HttpService {
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(clock / 1000) - 60 }));
+    return http;
+  }
+
+  it('retries an expired token ~1s after an ORDINARY failure (the unreachable-server lane is untouched)', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    clock += 1_001;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it('suppresses the retry for the limiter window after a 429, instead of hammering once a second', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => {
+      // What `refreshDeviceSecretArm` does when the mint answers 429.
+      http.noteRefreshRateLimited();
+      return null;
+    });
+    http.setAuthRefreshHandler(handler);
+
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Past the expired-token cooldown. Without the 429 discrimination this is
+    // where the client resumes one mint per second and holds the limiter down.
+    clock += BETWEEN_COOLDOWNS_MS;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Once the limiter's window has drained, exactly one probe goes out.
+    clock += LIMITER_WINDOW_MS;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it('holds a rate-limited client under the mint budget while requests keep arriving', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => {
+      http.noteRefreshRateLimited();
+      return null;
+    });
+    http.setAuthRefreshHandler(handler);
+
+    // One simulated minute of a busy app: a request every 250ms, each one
+    // driving the preflight/401 refresh lane.
+    for (let elapsed = 0; elapsed < 60_000; elapsed += 250) {
+      await http.refreshAccessToken('preflight');
+      clock += 250;
+    }
+
+    // The server's budget is 30/min. The unfixed client issues 60.
+    expect(handler.mock.calls.length).toBeLessThanOrEqual(2);
+  });
+
+  it('clears the lengthened cooldown once a refresh succeeds', async () => {
+    const http = expiredTokenClient();
+    const fresh = createJwt({ userId: 'u', exp: Math.floor(clock / 1000) + 900 });
+    const handler = jest
+      .fn<Promise<string | null>, []>()
+      .mockImplementationOnce(async () => {
+        http.noteRefreshRateLimited();
+        return null;
+      })
+      .mockImplementationOnce(async () => fresh)
+      // A later ordinary failure must be back on the short cooldown, proving the
+      // 429 state did not become sticky.
+      .mockImplementation(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    await http.refreshAccessToken('preflight');
+    clock += LIMITER_WINDOW_MS + 1;
+    expect(await http.refreshAccessToken('preflight')).toBe(fresh);
+
+    // The planted token is fresh, so this is the still-valid (15s) cooldown.
+    clock += 16_000;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(3);
+
+    clock += 16_000;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(4);
+  });
+
+  it('returns to the short cooldown when a later failure is NOT a 429', async () => {
+    const http = expiredTokenClient();
+    const handler = jest
+      .fn<Promise<string | null>, []>()
+      .mockImplementationOnce(async () => {
+        http.noteRefreshRateLimited();
+        return null;
+      })
+      // The limiter window passed and the endpoint is merely erroring now.
+      .mockImplementation(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    await http.refreshAccessToken('preflight');
+    clock += LIMITER_WINDOW_MS + 1;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(2);
+
+    clock += 1_001;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(3);
+  });
+});

package/src/__tests__/serviceTokenWorkloadFallback.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { OxyServices } from '../OxyServices';
+
+/**
+ * How an official service stops holding a secret WITHOUT a code change.
+ *
+ * `getServiceToken()` has always required an api key and secret. It now falls
+ * back to workload identity (ADR 0026) when there is none — which means the
+ * migration for each of Oxy's own services is "delete two environment
+ * variables", not "edit and redeploy an app".
+ *
+ * Three things have to be true for that to be safe, and each is asserted below:
+ *
+ *  1. A configured credential still wins. The fallback must not quietly change
+ *     how an already-working service authenticates.
+ *  2. With no credential AND no way to attest — a laptop, a CI box — the caller
+ *     gets the same "no credentials" error as before, not a confusing failure
+ *     from a container credentials endpoint that is not there.
+ *  3. The token is cached, so a service does not mint one per request.
+ */
+
+jest.mock('../server/workloadIdentity', () => ({
+  canAttestWorkloadIdentity: () => Boolean(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI),
+  requestWorkloadServiceToken: jest.fn(async () => ({
+    token: 'token-from-attestation',
+    expiresIn: 3600,
+    appName: 'Mention',
+  })),
+}));
+
+import { requestWorkloadServiceToken } from '../server/workloadIdentity';
+
+const attestations = requestWorkloadServiceToken as unknown as jest.Mock;
+
+function client() {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+describe('service token — workload fallback', () => {
+  const previous = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
+
+  beforeEach(() => {
+    attestations.mockClear();
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
+  });
+
+  afterAll(() => {
+    // Cleared by assignment rather than `delete`: Biome refuses `delete` on a
+    // property access, and an empty value reads as "cannot attest" everywhere
+    // that matters here.
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = previous ?? '';
+  });
+
+  it('attests when no credential is configured', async () => {
+    await expect(client().getServiceToken()).resolves.toBe('token-from-attestation');
+    expect(attestations).toHaveBeenCalledWith({ baseUrl: 'https://api.oxy.so' });
+  });
+
+  it('mints once and serves the cached token afterwards', async () => {
+    const oxy = client();
+
+    await oxy.getServiceToken();
+    await oxy.getServiceToken();
+
+    expect(attestations).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves a configured credential alone', async () => {
+    const oxy = client();
+    oxy.configureServiceAuth('oxy_dk_example', 'secret-example');
+    // The credential path goes to the network; failing there is fine — what
+    // matters is that it did not silently attest instead.
+    await oxy.getServiceToken().catch(() => undefined);
+
+    expect(attestations).not.toHaveBeenCalled();
+  });
+
+  it('still says "no credentials" where nothing can be attested', async () => {
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+
+    await expect(client().getServiceToken()).rejects.toThrow(/Service credentials not provided/);
+    expect(attestations).not.toHaveBeenCalled();
+  });
+});

package/src/crypto/__tests__/identityMove.test.ts

@@ -1,96 +1,138 @@
 /**
- * Moving an identity: both sides derive the same key and code; the responder
- * receives exactly the identity that was declared; a relay that swaps a key
- * gets a different code and cannot open the identity; receipts cannot be forged.
+ * Giving a root to Commons (ADR 0024 D6): both sides derive the same key and code;
+ * the responder receives exactly the declared identity; the initiator's key is
+ * committed before the responder's is chosen, so a relay cannot steer both codes
+ * together; and the receipt binds the move, root, both keys and the relayed
+ * ciphertext.
  */
 
+import { generateSecp256k1KeyPair } from '@oxy.so/protocol/secp256k1';
+import { signMessage } from '@oxy.so/protocol';
 import {
   buildMoveQrPayload,
+  createMoveCommitment,
   deriveMoveKey,
   deriveMoveSas,
+  digestMoveCiphertext,
   generateMoveEphemeralKeyPair,
-  IDENTITY_MOVE_ACTIONS,
   openMovedIdentity,
   parseMoveQrPayload,
   sealIdentityForMove,
-  signMoveAction,
+  signMoveReceipt,
+  verifyMoveCommitment,
   verifyMoveReceipt,
 } from '../identityMove';
-import { generateWebIdentity } from '../webIdentityCarrier';
+import { deriveIdentityFromMnemonic, generateWebIdentity } from '../webIdentityCarrier';
 
 const MOVE_ID = '0123456789abcdef0123456789abcdef';
-
-describe('a move between two honest carriers', () => {
-  it('delivers the declared identity and both screens show the same code', () => {
-    const identity = generateWebIdentity();
-    const web = generateMoveEphemeralKeyPair();
-    const commons = generateMoveEphemeralKeyPair();
-
-    const webKey = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
-    const commonsKey = deriveMoveKey(commons.privateKey, web.publicKey, MOVE_ID);
-    expect(Buffer.from(webKey).equals(Buffer.from(commonsKey))).toBe(true);
-
-    expect(deriveMoveSas(MOVE_ID, web.publicKey, commons.publicKey)).toMatch(/^\d{6}$/);
-
-    const sealed = sealIdentityForMove(identity, webKey, MOVE_ID);
-    expect(JSON.stringify(sealed)).not.toContain(identity.privateKey);
-
-    const received = openMovedIdentity(sealed, commonsKey, MOVE_ID, identity.publicKey);
-    expect(received).toEqual(identity);
+const MNEMONIC_24 =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art';
+
+function code(initiator: string, responder: string, commitment: string, moveId = MOVE_ID): string {
+  return deriveMoveSas({ moveId, initiatorEphemeralPublicKey: initiator, responderEphemeralPublicKey: responder, initiatorCommitment: commitment });
+}
+
+describe('a move between two honest sides', () => {
+  it('delivers the declared identity — 12 or 24 words — and both screens show the same code', () => {
+    for (const identity of [generateWebIdentity(), deriveIdentityFromMnemonic(MNEMONIC_24)]) {
+      const web = generateMoveEphemeralKeyPair();
+      const commons = generateMoveEphemeralKeyPair();
+      const { commitment, nonce } = createMoveCommitment(web.publicKey);
+      expect(verifyMoveCommitment(web.publicKey, nonce, commitment)).toBe(true);
+
+      const webKey = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
+      const commonsKey = deriveMoveKey(commons.privateKey, web.publicKey, MOVE_ID);
+      expect(Buffer.from(webKey).equals(Buffer.from(commonsKey))).toBe(true);
+      expect(code(web.publicKey, commons.publicKey, commitment)).toMatch(/^\d{6}$/);
+      expect(code(web.publicKey, commons.publicKey, commitment, MOVE_ID.toUpperCase())).toBe(code(web.publicKey, commons.publicKey, commitment));
+
+      const sealed = sealIdentityForMove(identity, webKey, MOVE_ID);
+      expect(JSON.stringify(sealed)).not.toContain(identity.privateKey);
+      expect(openMovedIdentity(sealed, commonsKey, MOVE_ID, identity.publicKey)).toEqual(identity);
+    }
   });
 });
 
-describe('a relay that substitutes a key', () => {
+describe('a relay that substitutes keys', () => {
+  it('cannot reveal a key the commitment does not open', () => {
+    const web = generateSecp256k1KeyPair();
+    const { commitment, nonce } = createMoveCommitment(web.publicKey);
+    expect(verifyMoveCommitment(generateSecp256k1KeyPair().publicKey, nonce, commitment)).toBe(false);
+    expect(verifyMoveCommitment(web.publicKey, 'ab'.repeat(32), commitment)).toBe(false);
+  });
+
   it('shows a different code on each screen and cannot open the identity', () => {
     const identity = generateWebIdentity();
     const web = generateMoveEphemeralKeyPair();
     const commons = generateMoveEphemeralKeyPair();
     const attacker = generateMoveEphemeralKeyPair();
+    const { commitment } = createMoveCommitment(web.publicKey);
+    const attackerCommitment = createMoveCommitment(attacker.publicKey).commitment;
 
-    // Web talks to the attacker thinking it is Commons; Commons talks to the attacker thinking it is the web.
-    const webSas = deriveMoveSas(MOVE_ID, web.publicKey, attacker.publicKey);
-    const commonsSas = deriveMoveSas(MOVE_ID, attacker.publicKey, commons.publicKey);
-    expect(webSas).not.toBe(commonsSas);
+    expect(code(web.publicKey, attacker.publicKey, commitment)).not.toBe(code(attacker.publicKey, commons.publicKey, attackerCommitment));
 
-    // Even sealed to the attacker, Commons' own key cannot open it.
     const sealedToAttacker = sealIdentityForMove(identity, deriveMoveKey(web.privateKey, attacker.publicKey, MOVE_ID), MOVE_ID);
     expect(() =>
       openMovedIdentity(sealedToAttacker, deriveMoveKey(commons.privateKey, web.publicKey, MOVE_ID), MOVE_ID, identity.publicKey),
     ).toThrow('could not be opened');
   });
 
-  it('refuses a sealed identity that is not the one the move declared', () => {
-    const declared = generateWebIdentity();
-    const other = generateWebIdentity();
-    const web = generateMoveEphemeralKeyPair();
-    const commons = generateMoveEphemeralKeyPair();
-    const key = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
-
-    const sealedOther = sealIdentityForMove(other, key, MOVE_ID);
-    expect(() => openMovedIdentity(sealedOther, key, MOVE_ID, declared.publicKey)).toThrow();
+  it('changes the code when any input changes, including the commitment', () => {
+    const web = generateSecp256k1KeyPair();
+    const commons = generateSecp256k1KeyPair();
+    const { commitment } = createMoveCommitment(web.publicKey);
+    const base = code(web.publicKey, commons.publicKey, commitment);
+    expect(code(web.publicKey, commons.publicKey, createMoveCommitment(web.publicKey).commitment)).not.toBe(base);
+    expect(code(web.publicKey, generateSecp256k1KeyPair().publicKey, commitment)).not.toBe(base);
+    expect(code(commons.publicKey, web.publicKey, commitment)).not.toBe(base);
   });
 
-  it('binds the ciphertext to its move id', () => {
-    const identity = generateWebIdentity();
+  it('refuses a sealed identity that is not the one the move declared, or another move’s ciphertext', () => {
+    const declared = generateWebIdentity();
     const web = generateMoveEphemeralKeyPair();
     const commons = generateMoveEphemeralKeyPair();
     const key = deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID);
-    const sealed = sealIdentityForMove(identity, key, MOVE_ID);
-    expect(() => openMovedIdentity(sealed, key, 'ffffffffffffffffffffffffffffffff', identity.publicKey)).toThrow();
+    expect(() => openMovedIdentity(sealIdentityForMove(generateWebIdentity(), key, MOVE_ID), key, MOVE_ID, declared.publicKey)).toThrow();
+    expect(() => openMovedIdentity(sealIdentityForMove(declared, key, MOVE_ID), key, 'ffffffffffffffffffffffffffffffff', declared.publicKey)).toThrow();
   });
 });
 
 describe('receipts', () => {
-  it('verify only when signed by the moved identity for this move', async () => {
+  function transfer() {
     const identity = generateWebIdentity();
-    const receipt = await signMoveAction(identity, IDENTITY_MOVE_ACTIONS.received, MOVE_ID);
-
-    expect(await verifyMoveReceipt(identity.publicKey, MOVE_ID, receipt)).toBe(true);
-    expect(await verifyMoveReceipt(identity.publicKey, 'ffffffffffffffffffffffffffffffff', receipt)).toBe(false);
-    expect(await verifyMoveReceipt(generateWebIdentity().publicKey, MOVE_ID, receipt)).toBe(false);
+    const web = generateMoveEphemeralKeyPair();
+    const commons = generateMoveEphemeralKeyPair();
+    const sealed = sealIdentityForMove(identity, deriveMoveKey(web.privateKey, commons.publicKey, MOVE_ID), MOVE_ID);
+    const claims = {
+      moveId: MOVE_ID,
+      rootPublicKey: identity.publicKey,
+      initiatorEphemeralPublicKey: web.publicKey,
+      responderEphemeralPublicKey: commons.publicKey,
+      ciphertextDigest: digestMoveCiphertext(sealed),
+    };
+    return { identity, sealed, claims };
+  }
+
+  it('verify for exactly the move, root, keys and ciphertext they were made over', async () => {
+    const { identity, sealed, claims } = transfer();
+    const receipt = await signMoveReceipt((message) => signMessage(message, identity.privateKey), claims);
+    expect(await verifyMoveReceipt(claims, receipt.signature)).toBe(true);
+
+    const other = { ...sealed, ciphertext: `${sealed.ciphertext.slice(0, -2)}00` };
+    for (const changed of [
+      { ...claims, moveId: 'ffffffffffffffffffffffffffffffff' },
+      { ...claims, responderEphemeralPublicKey: generateSecp256k1KeyPair().publicKey },
+      { ...claims, initiatorEphemeralPublicKey: generateSecp256k1KeyPair().publicKey },
+      { ...claims, ciphertextDigest: digestMoveCiphertext(other) },
+    ]) {
+      expect(await verifyMoveReceipt(changed, receipt.signature)).toBe(false);
+    }
+  });
 
-    const sealProof = await signMoveAction(identity, IDENTITY_MOVE_ACTIONS.seal, MOVE_ID);
-    expect(await verifyMoveReceipt(identity.publicKey, MOVE_ID, sealProof)).toBe(false);
+  it('are not the root’s if another key signed them', async () => {
+    const { claims } = transfer();
+    const forged = await signMoveReceipt((message) => signMessage(message, generateWebIdentity().privateKey), claims);
+    expect(await verifyMoveReceipt(claims, forged.signature)).toBe(false);
   });
 });