@amalgm/core 0.3.1 → 0.3.2

package/PURPOSE.md

@@ -122,9 +122,14 @@ source until each module is cut over.
     re-resolved against the verified catalog on every resume, and a changed
     plan becomes durable only after its installation and runtime prove healthy.
 22. **User access is short-lived and machine-bound.** A durable machine
-    credential may mint an audience- and scope-exact access token, but every
-    resource request also proves possession of that machine's key; Core owns
-    the claims and renewal law while hosts own keys, storage, signing, and HTTP.
+   credential may mint an audience- and scope-exact access token, but every
+   resource request also proves possession of that machine's key; Core owns
+   the claims and renewal law while hosts own keys, storage, signing, and HTTP.
+23. **Machine key replacement is an explicit recovery, never startup repair.**
+    Ordinary registration may pin an absent key or reuse the same key; replacing
+    it requires fresh user approval, proof of the candidate private key, and a
+    conditional swap from the expected old thumbprint. A completed swap is safe
+    to retry, and corrupt local key material remains visible until that ceremony.
 
 ## Five surfaces, one behavior
 

package/README.md

@@ -32,3 +32,8 @@ Rules of the house: zero runtime dependencies; nothing in `src/` imports
 shipped engine (the production source until cutover — PURPOSE.md axiom 9);
 tests are exams — each states a law, and a mutant must be convicted by at
 least one.
+
+Package releases use `.github/workflows/publish-package.yml`. A reviewed main
+commit is tagged exactly `v<package version>`; trusted npm publishing stages
+that package, and a maintainer approves the staged artifact with 2FA. Manual
+dirty-worktree publishing is not a release path.

package/dist/identity/authorization/index.d.ts

@@ -2,4 +2,5 @@ export * from './policy.js';
 export * from './claims.js';
 export * from './dpop.js';
 export * from './broker.js';
+export * from './key-transition.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/identity/authorization/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/identity/authorization/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/identity/authorization/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/dist/identity/authorization/index.js

@@ -2,4 +2,5 @@ export * from './policy.js';
 export * from './claims.js';
 export * from './dpop.js';
 export * from './broker.js';
+export * from './key-transition.js';
 //# sourceMappingURL=index.js.map

package/dist/identity/authorization/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/identity/authorization/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/identity/authorization/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/dist/identity/authorization/key-transition.d.ts

@@ -0,0 +1,19 @@
+export declare const AUTHORIZATION_KEY_RECOVERY_PURPOSE: "authorization_key_recovery";
+export type AuthorizationKeyTransition = 'pin' | 'unchanged' | 'rotate';
+export interface AuthorizationKeyTransitionInput {
+    readonly currentKeyThumbprint: string | null;
+    readonly presentedKeyThumbprint: string;
+    readonly recovery?: Readonly<{
+        readonly purpose: typeof AUTHORIZATION_KEY_RECOVERY_PURPOSE;
+        readonly expectedKeyThumbprint: string;
+    }>;
+}
+/** One closed rule for initial pinning, ordinary reuse, and explicit recovery. */
+export declare function authorizationKeyTransition(input: AuthorizationKeyTransitionInput): AuthorizationKeyTransition;
+export declare function isAuthorizationKeyThumbprint(value: unknown): value is string;
+export type AuthorizationKeyTransitionErrorCode = 'invalid_key_thumbprint' | 'invalid_recovery_purpose' | 'recovery_key_unchanged' | 'recovery_basis_mismatch' | 'key_mismatch';
+export declare class AuthorizationKeyTransitionError extends Error {
+    readonly code: AuthorizationKeyTransitionErrorCode;
+    constructor(code: AuthorizationKeyTransitionErrorCode);
+}
+//# sourceMappingURL=key-transition.d.ts.map

package/dist/identity/authorization/key-transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-transition.d.ts","sourceRoot":"","sources":["../../../src/identity/authorization/key-transition.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kCAAkC,EAAG,4BAAqC,CAAC;AAExF,MAAM,MAAM,0BAA0B,GAAG,KAAK,GAAG,WAAW,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,kCAAkC,CAAC;QAC5D,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;KACxC,CAAC,CAAC;CACJ;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,0BAA0B,CAsB5B;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5E;AAQD,MAAM,MAAM,mCAAmC,GAC3C,wBAAwB,GACxB,0BAA0B,GAC1B,wBAAwB,GACxB,yBAAyB,GACzB,cAAc,CAAC;AAEnB,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,EAAE,mCAAmC,CAAC;gBAEvC,IAAI,EAAE,mCAAmC;CAKtD"}

package/dist/identity/authorization/key-transition.js

@@ -0,0 +1,44 @@
+export const AUTHORIZATION_KEY_RECOVERY_PURPOSE = 'authorization_key_recovery';
+/** One closed rule for initial pinning, ordinary reuse, and explicit recovery. */
+export function authorizationKeyTransition(input) {
+    assertKeyThumbprint(input.presentedKeyThumbprint);
+    if (input.currentKeyThumbprint !== null)
+        assertKeyThumbprint(input.currentKeyThumbprint);
+    if (input.recovery) {
+        assertKeyThumbprint(input.recovery.expectedKeyThumbprint);
+        if (input.recovery.purpose !== AUTHORIZATION_KEY_RECOVERY_PURPOSE) {
+            throw new AuthorizationKeyTransitionError('invalid_recovery_purpose');
+        }
+        if (input.presentedKeyThumbprint === input.recovery.expectedKeyThumbprint) {
+            throw new AuthorizationKeyTransitionError('recovery_key_unchanged');
+        }
+        if (input.currentKeyThumbprint === input.presentedKeyThumbprint)
+            return 'unchanged';
+        if (input.currentKeyThumbprint !== input.recovery.expectedKeyThumbprint) {
+            throw new AuthorizationKeyTransitionError('recovery_basis_mismatch');
+        }
+        return 'rotate';
+    }
+    if (input.currentKeyThumbprint === null)
+        return 'pin';
+    if (input.currentKeyThumbprint === input.presentedKeyThumbprint)
+        return 'unchanged';
+    throw new AuthorizationKeyTransitionError('key_mismatch');
+}
+export function isAuthorizationKeyThumbprint(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value);
+}
+function assertKeyThumbprint(value) {
+    if (!isAuthorizationKeyThumbprint(value)) {
+        throw new AuthorizationKeyTransitionError('invalid_key_thumbprint');
+    }
+}
+export class AuthorizationKeyTransitionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = 'AuthorizationKeyTransitionError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=key-transition.js.map

package/dist/identity/authorization/key-transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-transition.js","sourceRoot":"","sources":["../../../src/identity/authorization/key-transition.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kCAAkC,GAAG,4BAAqC,CAAC;AAaxF,kFAAkF;AAClF,MAAM,UAAU,0BAA0B,CACxC,KAAsC;IAEtC,mBAAmB,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,oBAAoB,KAAK,IAAI;QAAE,mBAAmB,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAEzF,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;QAC1D,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,KAAK,kCAAkC,EAAE,CAAC;YAClE,MAAM,IAAI,+BAA+B,CAAC,0BAA0B,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,KAAK,CAAC,sBAAsB,KAAK,KAAK,CAAC,QAAQ,CAAC,qBAAqB,EAAE,CAAC;YAC1E,MAAM,IAAI,+BAA+B,CAAC,wBAAwB,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,sBAAsB;YAAE,OAAO,WAAW,CAAC;QACpF,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,QAAQ,CAAC,qBAAqB,EAAE,CAAC;YACxE,MAAM,IAAI,+BAA+B,CAAC,yBAAyB,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,KAAK,CAAC,oBAAoB,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,sBAAsB;QAAE,OAAO,WAAW,CAAC;IACpF,MAAM,IAAI,+BAA+B,CAAC,cAAc,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,CAAC,4BAA4B,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,+BAA+B,CAAC,wBAAwB,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AASD,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAC/C,IAAI,CAAsC;IAEnD,YAAY,IAAyC;QACnD,KAAK,CAAC,IAAI,CAAC,CAAC;QACZ,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/docs/authorization.md

@@ -20,6 +20,9 @@ needs.
    single-flights concurrent renewal, and performs no silent auth fallback.
 5. Audiences and scopes are closed sets. Adding a consumer changes this module
    and its tests before any issuer or verifier accepts it.
+6. A machine key is pinned once. Replacement requires an explicit, browser-
+   approved recovery bound to the expected old thumbprint and a different
+   candidate key; retrying an already completed replacement is idempotent.
 
 ## Public surface
 
@@ -28,6 +31,7 @@ Import `@amalgm/core/authorization` for:
 - `AUTHORIZATION_POLICY` and the audience/scope types;
 - access-token and DPoP claim contracts;
 - URL and method normalization;
+- the closed initial-pin, ordinary-reuse, and explicit-recovery transition;
 - `CredentialBroker`, whose issuer and signer effects are injected by Shell.
 
 The default access lifetime is 15 minutes. Cached credentials refresh at least

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/core",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "The Amalgm kernel SDK — identity, transport, supervision, and host capability contracts behind host-injected adapters.",
   "type": "module",
   "license": "UNLICENSED",
@@ -67,8 +67,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/",
-    "test:parity": "npm run build && node --test tests/parity/",
+    "test": "npm run build && node --test",
     "examine:machine-setup": "npm run build && node --test tests/supervision/installation-plan.test.js tests/machine-setup/examination.test.js",
     "examine:user-ground": "npm run build && npm --prefix ../amalgm-live run build && node --test examinations/user-ground/login.examination.mjs"
   },