@typedstandards/verify-core 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,80 @@ references are to `npstorey/civic-ai-tools-website` (#119 is the offline-crypto
 hardening arc; #116 is the standalone-verifier arc this package was extracted
 in).
 
+## 0.13.0 — 2026-09-27
+
+The core-minors release (typedstandards#113, shipped in #114, #115 and #118). **A minor bump** —
+`LIFECYCLE_STATUSES` gains `superseded`, so a consumer with an exhaustive `switch` or `Record` over
+`LifecycleStatus` needs the new case, and `verifyLifecycleChain` now moves status only on a node
+whose key is bound to the signer it names and that carries its required fields.
+
+- **A lifecycle attestation moves status only when its signing key is bound to the signer it names
+  (typedstandards#113).** `verifyLifecycleChain` takes an optional fourth argument, a
+  `LifecycleKeyBinding` (`targetPublicKey`, `registry`, `registryProvenance`), and a carried node
+  signer-matches only when its `signer.identifier` equals the target's and its key is bound:
+  - a key-derived identifier (`did:key:`) binds by derivation from the node's own public key, the rule
+    check #14 applies to a record;
+  - any other identifier binds when the node is signed by the target record's own key
+    (`targetPublicKey`), or when a registry fetched from its declared URL (`registryProvenance:
+    'declared-url'`) lists the node's `(kid, publicKey)` under that identifier, read by the rules of
+    checks #5 and #14. A registry carried in a bundle, or one with no stated provenance, never binds.
+
+  A node that is not bound stays in `chain` and does not move status. A caller that passes no binding
+  material gets a status moved only by `did:key` signers. `LifecycleAttestationView` gains an optional
+  `keyBound`, set by `verifyLifecycleChain`, and `CarriedLifecycleNode.signature` gains an optional
+  `kid`. `resolveLifecycleFromChain` is unchanged.
+- **A carried lifecycle node that lacks a required payload field moves no status (typedstandards#113,
+  spec §8.12.3).** In `verifyLifecycleChain`, a node that lacks a field `ATTESTATION_REQUIRED_FIELDS`
+  lists for its sub-type (absent, null or the empty string: a `withdraws` with no `reason`, a
+  `reinstates` with no `priorWithdrawalNodeId`, a `supersedes` or `revises` with no
+  `successorNodeId`) stays in `chain` with `signerMatchesTarget` false, whoever signed it, and does not
+  move the status. `LifecycleAttestationView` gains an optional `missingFields`, set by
+  `verifyLifecycleChain` on every view: the fields the node lacks, by name, empty when it lacks none.
+  `resolveLifecycleFromChain` and `checkAttestationNode` are unchanged.
+- **On typedstandards.org** (the site's verifier; not part of this package's API): the carried lifecycle
+  chain is resolved with the record's own signing key, and with the trust registry only when it was
+  fetched from the record's declared URL. A carried lifecycle event that names the record's signer and
+  lacks a required payload field adds one #10 line at `attention`, whose detail names the field, and
+  the #10 row lists the event under the fields it lacks. A third party's event that lacks one reads as
+  any third-party event does and adds no line (the owner's correction at the P5-fix gate, per G0 D6 as
+  corrected).
+- **`superseded` is a lifecycle status (typedstandards#113, G0 D2).** `LIFECYCLE_STATUSES` is
+  `active`, `withdrawn`, `superseded`. `resolveLifecycleFromChain` reads the status from the latest
+  signer-matched node among `withdraws`, `reinstates` and `supersedes`: a `supersedes` reads
+  `superseded`; a `reinstates` reads `superseded` when a signer-matched `supersedes` precedes it and
+  `active` otherwise; a later `withdraws` reads `withdrawn`. `revises` is surfaced in `chain` and never
+  moves the status. `LifecycleResolution` gains `supersededAt` and `successorNodeId`, from the latest
+  counting `supersedes`. For a chain of `withdraws` and `reinstates` only, the output is unchanged.
+  `resolveLifecycleFromLegacyColumns` never derives `superseded`.
+  - `LifecycleAttestationView` gains optional `successorNodeId` and `namesTarget` (set by
+    `verifyLifecycleChain`: the node's `signer.identifier` equals the target's, bound or not).
+  - `CommitmentLifecycleState.status` widens to `'superseded'`, with optional `supersededAt` and
+    `successorNodeId`. `verifyRecord`'s STATE path still reads only the withdrawal columns.
+  - New constants `ATTESTATION_SUPERSEDES`, `ATTESTATION_REVISES`, `ATTESTATION_CORROBORATES`,
+    `ATTESTATION_CONTRADICTS`, and the lists `LIFECYCLE_STATUS_ATTESTATION_TYPES` (withdraws,
+    reinstates, supersedes) and `LIFECYCLE_CHAIN_ATTESTATION_TYPES` (those and revises).
+    `LifecycleAttestationType` and `LIFECYCLE_ATTESTATION_TYPES` stay `withdraws` and `reinstates`,
+    the withdrawal/reinstatement pair. produce-core also emits `supersedes` and `revises`, so they are
+    not the set it emits, and no verify-core check reads them.
+- **A per-node authorization check, `checkAttestationNode` (typedstandards#113, G0 D6 and D4).** For
+  `withdraws`, `reinstates`, `supersedes`, `revises`, `corroborates` and `contradicts`, in order:
+  integrity and signature; the key binding, by `verifyLifecycleChain`'s rule; then the sub-type's
+  authorization rule (spec §8.12.3). Publisher-only (the four lifecycle sub-types) runs when the
+  attested record's signer and signing key are supplied, and otherwise reads `not_checked`; a node
+  naming another signer reads `other_signer`, and one naming the record's signer under a key not bound
+  to it reads `publisher_key_unbound`. Any-with-binding (`corroborates`, `contradicts`) needs the key
+  bound to the node's own identifier (a `did:key` by derivation; any other identifier only by a
+  registry fetched from its declared URL) and a `signer.bindingTier` in `BINDING_TIERS`
+  (`pseudonymous`, `oauth`, `orcid`, `did-web`, `notarized`, `platform`). The result names each
+  required §8.12.1 payload field the node lacks, in `missingFields`; it moves no status. New exports:
+  `checkAttestationNode`, `ATTESTATION_AUTHORIZATION_RULES`, `ATTESTATION_REQUIRED_FIELDS`,
+  `ATTESTATION_AUTHORIZATION_STATUSES`, `BINDING_TIERS`, and the types
+  `AttestationAuthorizationRule`, `AttestationAuthorizationStatus`, `AttestationCheckContext`,
+  `AttestationCheck`.
+- **On typedstandards.org:** `superseded` reads `normal` ("Superseded by the publisher") and the #10
+  row names the successor. A carried lifecycle event that names the record's signer, under a key not
+  bound to it, adds one #10 line at `attention`; a third party's event adds nothing.
+
 ## 0.12.0 — 2026-09-24
 
 The certificate-chain split (typedstandards#100, shipped in #106). **A minor bump** — `ChainFailReason`

package/dist/attestation.d.ts

@@ -1,5 +1,23 @@
 export declare const ATTESTATION_WITHDRAWS = "attestation/withdraws/v1";
 export declare const ATTESTATION_REINSTATES = "attestation/reinstates/v1";
+export declare const ATTESTATION_SUPERSEDES = "attestation/supersedes/v1";
+export declare const ATTESTATION_REVISES = "attestation/revises/v1";
+export declare const ATTESTATION_CORROBORATES = "attestation/corroborates/v1";
+export declare const ATTESTATION_CONTRADICTS = "attestation/contradicts/v1";
+/** The withdrawal/reinstatement pair: the two lifecycle sub-types the legacy
+ *  `withdrawnAt` / `reinstatedAt` columns also record (spec §8.10.4). produce-core's
+ *  `EmittableAttestationType` includes this union beside the other sub-types it
+ *  emits, `supersedes` and `revises` among them, so it is not the set produce-core
+ *  emits. No verify-core check reads it: the lifecycle reads
+ *  `LIFECYCLE_STATUS_ATTESTATION_TYPES` and `LIFECYCLE_CHAIN_ATTESTATION_TYPES`. */
 export type LifecycleAttestationType = typeof ATTESTATION_WITHDRAWS | typeof ATTESTATION_REINSTATES;
-/** The lifecycle sub-type URIs the verify side resolves (spec §8.12.1). */
+/** The values of `LifecycleAttestationType`, the withdrawal/reinstatement pair. Not
+ *  the set produce-core emits, and not read by any verify-core check (see
+ *  `LifecycleAttestationType`). */
 export declare const LIFECYCLE_ATTESTATION_TYPES: readonly string[];
+/** The sub-types that move a record's lifecycle status (spec §8.10.6: `active`,
+ *  `withdrawn`, `superseded`). `revises` and `publishes` never do. */
+export declare const LIFECYCLE_STATUS_ATTESTATION_TYPES: readonly string[];
+/** The publisher-only lifecycle sub-types surfaced in a record's lifecycle chain:
+ *  the status-moving three, and `revises`, which is shown but moves nothing. */
+export declare const LIFECYCLE_CHAIN_ATTESTATION_TYPES: readonly string[];

package/dist/attestation.js

@@ -1,12 +1,31 @@
-// Lifecycle attestation sub-type URIs (spec §8.10, §8.12.1) — browser-safe
-// constants. The server `attestation.ts` builder (which mints nodes and so needs
-// Node's `crypto.randomUUID`) re-exports these from verify-core, keeping a single
+// Attestation sub-type URIs (spec §8.10, §8.12.1) — browser-safe constants. The
+// server `attestation.ts` builder (which mints nodes and so needs Node's
+// `crypto.randomUUID`) re-exports these from verify-core, keeping a single
 // definition of the URIs the verify side dispatches on. verify-core never builds
 // nodes — it only verifies and orders them — so it carries the constants alone.
 export const ATTESTATION_WITHDRAWS = 'attestation/withdraws/v1';
 export const ATTESTATION_REINSTATES = 'attestation/reinstates/v1';
-/** The lifecycle sub-type URIs the verify side resolves (spec §8.12.1). */
+export const ATTESTATION_SUPERSEDES = 'attestation/supersedes/v1';
+export const ATTESTATION_REVISES = 'attestation/revises/v1';
+export const ATTESTATION_CORROBORATES = 'attestation/corroborates/v1';
+export const ATTESTATION_CONTRADICTS = 'attestation/contradicts/v1';
+/** The values of `LifecycleAttestationType`, the withdrawal/reinstatement pair. Not
+ *  the set produce-core emits, and not read by any verify-core check (see
+ *  `LifecycleAttestationType`). */
 export const LIFECYCLE_ATTESTATION_TYPES = [
     ATTESTATION_WITHDRAWS,
     ATTESTATION_REINSTATES,
 ];
+/** The sub-types that move a record's lifecycle status (spec §8.10.6: `active`,
+ *  `withdrawn`, `superseded`). `revises` and `publishes` never do. */
+export const LIFECYCLE_STATUS_ATTESTATION_TYPES = [
+    ATTESTATION_WITHDRAWS,
+    ATTESTATION_REINSTATES,
+    ATTESTATION_SUPERSEDES,
+];
+/** The publisher-only lifecycle sub-types surfaced in a record's lifecycle chain:
+ *  the status-moving three, and `revises`, which is shown but moves nothing. */
+export const LIFECYCLE_CHAIN_ATTESTATION_TYPES = [
+    ...LIFECYCLE_STATUS_ATTESTATION_TYPES,
+    ATTESTATION_REVISES,
+];

package/dist/lifecycle.d.ts

@@ -1,5 +1,8 @@
 import type { SignerIdentity } from './types.ts';
-export declare const LIFECYCLE_STATUSES: readonly ["active", "withdrawn"];
+import type { TrustRegistry, TrustRegistryProvenance } from './trust-registry.ts';
+/** Lifecycle status (spec §8.10.6). Only the attestation chain derives
+ *  `superseded`; the legacy columns (§8.10.4) know no supersession. */
+export declare const LIFECYCLE_STATUSES: readonly ["active", "withdrawn", "superseded"];
 export type LifecycleStatus = (typeof LIFECYCLE_STATUSES)[number];
 /** Which representation determined the lifecycle status. `none` = never
  *  withdrawn, no attestations and no legacy columns. */
@@ -15,6 +18,8 @@ export interface LifecycleAttestationView {
     reason?: string;
     effectiveAt?: string;
     priorWithdrawalNodeId?: string;
+    /** `supersedes` / `revises`: the successor node's id. */
+    successorNodeId?: string;
     /** Ed25519ph signature over the recomputed nodeId; null when unsigned. */
     signatureValid: boolean | null;
     /** Recomputed envelope hash equals the stored nodeId (integrity). */
@@ -25,9 +30,24 @@ export interface LifecycleAttestationView {
     /** Rekor inclusion-proof entry present (presence only; per-attestation Rekor
      *  cryptographic verification is a follow-up). */
     hasRekor: boolean;
-    /** Publisher-only conformance (§8.12.3): the attestation's signer.identifier
-     *  matches the target content node's signer.identifier. */
+    /** Whether the node counts toward the status (§8.12.3). The attestation's
+     *  signer.identifier matches the target content node's signer.identifier. On a
+     *  view built by `verifyLifecycleChain`, it also requires `keyBound`, and that the
+     *  node carries every payload field §8.12.1 requires of its sub-type
+     *  (`missingFields` empty): §8.12.3's conformance covers the payload fields. */
     signerMatchesTarget: boolean;
+    /** Set by `verifyLifecycleChain`: the node's signing key is bound to the
+     *  signer it names (see `verifyLifecycleChain`). Absent on views built
+     *  elsewhere. */
+    keyBound?: boolean;
+    /** Set by `verifyLifecycleChain`: the node's `signer.identifier` equals the
+     *  target's, whether or not its key is bound. Absent on views built elsewhere. */
+    namesTarget?: boolean;
+    /** Set by `verifyLifecycleChain`: each payload field §8.12.1 requires of the
+     *  node's sub-type (`ATTESTATION_REQUIRED_FIELDS`) that the node lacks (absent,
+     *  null or the empty string), by name; empty when it lacks none. A node that
+     *  lacks one does not count toward the status. Absent on views built elsewhere. */
+    missingFields?: string[];
 }
 export interface LifecycleResolution {
     status: LifecycleStatus;
@@ -40,6 +60,10 @@ export interface LifecycleResolution {
     withdrawnReason?: string;
     reinstatedAt?: string;
     reinstatedReason?: string;
+    /** The latest counting `supersedes`: its envelope timestamp. */
+    supersededAt?: string;
+    /** The latest counting `supersedes`: its `successorNodeId`. */
+    successorNodeId?: string;
 }
 export interface AttestationVerifyResult {
     /** The recomputed envelope hash (= nodeId by construction). */
@@ -62,18 +86,33 @@ export declare function verifyAttestationNode(node: Record<string, unknown>, sto
 } | null): AttestationVerifyResult;
 /**
  * Check #10 (chain path) — derive lifecycle status from a set of verified
- * attestation views (spec §8.10.1, §8.10.3). The current status is the latest
- * signer-matched lifecycle attestation by envelope timestamp: `withdraws` →
- * withdrawn, `reinstates` → active. Non-signer-matched attestations are kept in
- * the surfaced chain for transparency but do NOT move the status (retention
- * asymmetry, §8.10.3).
+ * attestation views (spec §8.10.1, §8.10.3, §8.10.6; typedstandards#113 G0 D2).
+ *
+ * The chain holds the publisher-only lifecycle sub-types
+ * (`LIFECYCLE_CHAIN_ATTESTATION_TYPES`: withdraws, reinstates, supersedes,
+ * revises), ordered by envelope timestamp, ties by nodeId. The status is read
+ * from the latest signer-matched node among withdraws, reinstates and
+ * supersedes (`LIFECYCLE_STATUS_ATTESTATION_TYPES`):
+ *   - `withdraws` → withdrawn;
+ *   - `supersedes` → superseded;
+ *   - `reinstates` → superseded when a signer-matched `supersedes` precedes it in
+ *     chain order, active otherwise.
+ * `revises` is surfaced in the chain and never moves the status (§8.10.5: no
+ * deprecation signal). Non-signer-matched attestations are kept in the surfaced
+ * chain for transparency but do NOT move the status (retention asymmetry,
+ * §8.10.3). The latest signer-matched `supersedes` names the successor and the
+ * supersession time.
+ *
+ * For a chain of withdraws and reinstates only, the output is what it was before
+ * `superseded` existed.
  */
 export declare function resolveLifecycleFromChain(views: LifecycleAttestationView[]): LifecycleResolution;
 /**
  * Check #10 (legacy fallback) — derive lifecycle status from the pre-PR3
  * `withdrawnAt` / `reinstatedAt` columns (spec §8.10.4). Used when a content node
  * has no attestation envelopes. Withdrawn iff `withdrawnAt` is set and
- * `reinstatedAt` is not.
+ * `reinstatedAt` is not. It never derives `superseded`: the columns record no
+ * supersession.
  */
 export declare function resolveLifecycleFromLegacyColumns(columns: {
     withdrawnAt?: string | null;
@@ -94,11 +133,24 @@ export interface CarriedLifecycleNode {
         signature?: string;
         publicKey?: string;
         algorithm?: string;
+        kid?: string;
     } | null;
     /** Presence flags (surfaced; per-attestation TSA/Rekor depth is a follow-up). */
     hasTimestamp?: boolean;
     hasRekor?: boolean;
 }
+/** What a caller holds that can bind a lifecycle attestation's signing key to
+ *  the signer it names (see `verifyLifecycleChain`). */
+export interface LifecycleKeyBinding {
+    /** The target record's own signing key (the base64 SPKI `publicKey` of its
+     *  signature envelope). */
+    targetPublicKey?: string;
+    /** A parsed trust registry. */
+    registry?: TrustRegistry;
+    /** Where `registry` came from. Only `declared-url` can bind a key; absent is
+     *  treated as `bundle`. */
+    registryProvenance?: TrustRegistryProvenance;
+}
 /**
  * Resolve lifecycle (#10) INDEPENDENTLY from carried signed attestation nodes —
  * the browser/offline path that reaches `source: 'attestation-chain'` with no
@@ -112,9 +164,107 @@ export interface CarriedLifecycleNode {
  *   - INTEGRITY: the recomputed envelope hash MUST equal the stored `nodeId`.
  *   - SIGNATURE: the Ed25519(ph) signature MUST verify over that hash.
  * A node failing any of these is EXCLUDED (a forged/tampered/misdirected transition
- * cannot move the status). Surviving nodes go to `resolveLifecycleFromChain`, which
- * applies the §8.10.3 retention asymmetry (a valid but non-signer-matched attestation
- * is surfaced in the chain yet does NOT move the publisher's status). That shared
- * resolver is unchanged, so the server route's output stays byte-identical.
+ * cannot move the status). A surviving node is signer-matched only when its
+ * `signer.identifier` equals the target's AND its signing key is bound to that
+ * identifier (`keyBound`), by what `binding` supplies:
+ *   - a key-derived identifier (`did:key:`) binds by derivation from the node's own
+ *     public key, the rule check #14 applies to a record;
+ *   - any other identifier binds by `binding.targetPublicKey` (the node is signed by
+ *     the target record's own key), or by `binding.registry` when
+ *     `binding.registryProvenance` is `declared-url` and it lists the node's
+ *     `(kid, publicKey)` under that identifier, read by the rules of checks #5 and
+ *     #14. A registry carried in a bundle, or with no stated provenance, never binds.
+ * Each view records `namesTarget` (the identifiers are equal) beside `keyBound`, so a
+ * reader can tell a third party's node from one that names the publisher under a key
+ * not bound to it.
+ * A surviving node that lacks a payload field §8.12.1 requires of its sub-type
+ * (§8.12.3; `ATTESTATION_REQUIRED_FIELDS`, absent, null or the empty string) is not
+ * signer-matched either, whoever signed it: it stays in the chain, names the fields
+ * in `missingFields`, and does not move the status.
+ * Surviving nodes go to `resolveLifecycleFromChain`, which applies the §8.10.3
+ * retention asymmetry (a valid but non-signer-matched attestation is surfaced in the
+ * chain yet does NOT move the publisher's status).
+ */
+export declare function verifyLifecycleChain(carried: CarriedLifecycleNode[], contentNodeId: string, targetSignerIdentifier: string, binding?: LifecycleKeyBinding): LifecycleResolution;
+/** A sub-type's authorization rule (spec §8.12.1). */
+export type AttestationAuthorizationRule = 'publisher-only' | 'any-with-binding';
+/** The rule of each sub-type `checkAttestationNode` checks. `publishes`,
+ *  `locatedAt` and the specific-role-required sub-types have none here. */
+export declare const ATTESTATION_AUTHORIZATION_RULES: Readonly<Record<string, AttestationAuthorizationRule>>;
+/** Each checked sub-type's required payload fields (spec §8.12.1), beyond the
+ *  structural primitive. Optional fields (`effectiveAt`, a reinstatement's
+ *  `reason`, `reasoning`) are not listed. */
+export declare const ATTESTATION_REQUIRED_FIELDS: Readonly<Record<string, readonly string[]>>;
+/** The `signer.bindingTier` values an any-with-binding node may carry: the §8.5
+ *  graded identity ladder, and `platform` (spec §8.1.1). */
+export declare const BINDING_TIERS: readonly ["pseudonymous", "oauth", "orcid", "did-web", "notarized", "platform"];
+/**
+ * What `checkAttestationNode` reads for a node, first failure first:
+ *   - `node_id_mismatch` — the recomputed envelope hash is not the stored nodeId;
+ *   - `signature_invalid` — the signature does not verify over it;
+ *   - `unsigned` — the node carries no signature, so nothing can be bound;
+ *   - `not_checked` — publisher-only with no attested record supplied, or a
+ *     sub-type this check has no rule for;
+ *   - `other_signer` — publisher-only: the node names a signer other than the
+ *     attested record's, a third party's event;
+ *   - `publisher_key_unbound` — publisher-only: the node names the attested
+ *     record's signer, but its signing key is not bound to that signer;
+ *   - `key_unbound` — any-with-binding: the signing key is not bound to the signer
+ *     the node names;
+ *   - `binding_tier_off_ladder` — any-with-binding: `signer.bindingTier` is not in
+ *     `BINDING_TIERS`;
+ *   - `authorized` — the sub-type's rule holds.
+ */
+export declare const ATTESTATION_AUTHORIZATION_STATUSES: readonly ["authorized", "not_checked", "other_signer", "publisher_key_unbound", "key_unbound", "binding_tier_off_ladder", "unsigned", "signature_invalid", "node_id_mismatch"];
+export type AttestationAuthorizationStatus = (typeof ATTESTATION_AUTHORIZATION_STATUSES)[number];
+/** What a caller holds for `checkAttestationNode`. */
+export interface AttestationCheckContext {
+    /** The attested record: its `signer.identifier`, and the base64 SPKI
+     *  `publicKey` of its signature envelope. The publisher-only rule runs only
+     *  when this is supplied. */
+    target?: {
+        signerIdentifier: string;
+        publicKey: string;
+    };
+    /** A parsed trust registry that may bind the node's key to the identifier it
+     *  names. */
+    registry?: TrustRegistry;
+    /** Where `registry` came from. Only `declared-url` can bind a key; absent is
+     *  treated as `bundle`. */
+    registryProvenance?: TrustRegistryProvenance;
+}
+export interface AttestationCheck {
+    /** The recomputed envelope hash. */
+    nodeId: string;
+    type: string;
+    /** The sub-type's rule; null for a sub-type this check has none for. */
+    rule: AttestationAuthorizationRule | null;
+    nodeIdMatches: boolean;
+    signatureValid: boolean | null;
+    /** The signing key is bound to the signer the node names (see `status`). */
+    keyBound: boolean;
+    status: AttestationAuthorizationStatus;
+    /** Each required §8.12.1 payload field the node lacks (absent, null or the
+     *  empty string), by name. Reported only; it does not change `status`. */
+    missingFields: string[];
+}
+/**
+ * Check one `attestation/*` node on its own (spec §8.12.3), for `withdraws`,
+ * `reinstates`, `supersedes`, `revises`, `corroborates` and `contradicts`, in
+ * order:
+ *   1. integrity and signature, as `verifyAttestationNode` reads them;
+ *   2. the key binding, by the rule `verifyLifecycleChain` applies: a key-derived
+ *      identifier binds by derivation; any other identifier binds by a registry
+ *      fetched from its declared URL, and, for a publisher-only node only, by the
+ *      attested record's own signing key;
+ *   3. the sub-type's authorization rule:
+ *      - publisher-only (the four lifecycle sub-types) runs when `context.target`
+ *        is supplied, and otherwise reads `not_checked`. A node naming another
+ *        signer reads `other_signer`; one naming the target's signer under a key
+ *        not bound to it reads `publisher_key_unbound`;
+ *      - any-with-binding (`corroborates`, `contradicts`) needs the key bound and a
+ *        `signer.bindingTier` in `BINDING_TIERS`.
+ * It also names each required §8.12.1 payload field the node lacks. Pure; it moves
+ * no status: `resolveLifecycleFromChain` alone derives the lifecycle.
  */
-export declare function verifyLifecycleChain(carried: CarriedLifecycleNode[], contentNodeId: string, targetSignerIdentifier: string): LifecycleResolution;
+export declare function checkAttestationNode(carried: CarriedLifecycleNode, context?: AttestationCheckContext): AttestationCheck;

package/dist/lifecycle.js

@@ -1,11 +1,11 @@
 // Lifecycle attestation checks (spec §9.2 check #10, §8.10) — browser-safe pure
 // logic.
 //
-// Lifecycle state (withdrawn / active) is derived from a chain of separately-
-// signed `attestation/*` nodes referencing the content node by `targetNodeId`,
-// each verified independently. Backwards-compat (§8.10.4): when no attestation
-// envelopes are present, the legacy `withdrawnAt` / `reinstatedAt` columns are
-// honored instead.
+// Lifecycle state (active / withdrawn / superseded) is derived from a chain of
+// separately-signed `attestation/*` nodes referencing the content node by
+// `targetNodeId`, each verified independently. Backwards-compat (§8.10.4): when
+// no attestation envelopes are present, the legacy `withdrawnAt` /
+// `reinstatedAt` columns are honored instead.
 //
 // This file holds only the PURE ordering / status-derivation / per-node
 // verification logic (factored from the server `verify.ts`). The DB + blob fetch
@@ -15,9 +15,14 @@
 // status/withdrawnAt/reason) rather than re-running the chain — verifying the
 // signed attestation chain independently in the browser is civic-ai-tools-website#119.
 import { computeEnvelopeHash } from "./canonicalization.js";
-import { verifySignature } from "./signature.js";
-import { ATTESTATION_WITHDRAWS, ATTESTATION_REINSTATES, LIFECYCLE_ATTESTATION_TYPES, } from "./attestation.js";
-export const LIFECYCLE_STATUSES = ['active', 'withdrawn'];
+import { extractRawPublicKey, verifySignature } from "./signature.js";
+import { checkSignerIdentity } from "./checks.js";
+import { isKeyDerivedIdentifier } from "./did-key.js";
+import { verifyKeyTrust } from "./trust-registry.js";
+import { ATTESTATION_WITHDRAWS, ATTESTATION_REINSTATES, ATTESTATION_SUPERSEDES, ATTESTATION_REVISES, ATTESTATION_CORROBORATES, ATTESTATION_CONTRADICTS, LIFECYCLE_STATUS_ATTESTATION_TYPES, LIFECYCLE_CHAIN_ATTESTATION_TYPES, } from "./attestation.js";
+/** Lifecycle status (spec §8.10.6). Only the attestation chain derives
+ *  `superseded`; the legacy columns (§8.10.4) know no supersession. */
+export const LIFECYCLE_STATUSES = ['active', 'withdrawn', 'superseded'];
 /** Which representation determined the lifecycle status. `none` = never
  *  withdrawn, no attestations and no legacy columns. */
 export const LIFECYCLE_SOURCES = [
@@ -50,20 +55,46 @@ function compareLifecycleOrder(a, b) {
 }
 /**
  * Check #10 (chain path) — derive lifecycle status from a set of verified
- * attestation views (spec §8.10.1, §8.10.3). The current status is the latest
- * signer-matched lifecycle attestation by envelope timestamp: `withdraws` →
- * withdrawn, `reinstates` → active. Non-signer-matched attestations are kept in
- * the surfaced chain for transparency but do NOT move the status (retention
- * asymmetry, §8.10.3).
+ * attestation views (spec §8.10.1, §8.10.3, §8.10.6; typedstandards#113 G0 D2).
+ *
+ * The chain holds the publisher-only lifecycle sub-types
+ * (`LIFECYCLE_CHAIN_ATTESTATION_TYPES`: withdraws, reinstates, supersedes,
+ * revises), ordered by envelope timestamp, ties by nodeId. The status is read
+ * from the latest signer-matched node among withdraws, reinstates and
+ * supersedes (`LIFECYCLE_STATUS_ATTESTATION_TYPES`):
+ *   - `withdraws` → withdrawn;
+ *   - `supersedes` → superseded;
+ *   - `reinstates` → superseded when a signer-matched `supersedes` precedes it in
+ *     chain order, active otherwise.
+ * `revises` is surfaced in the chain and never moves the status (§8.10.5: no
+ * deprecation signal). Non-signer-matched attestations are kept in the surfaced
+ * chain for transparency but do NOT move the status (retention asymmetry,
+ * §8.10.3). The latest signer-matched `supersedes` names the successor and the
+ * supersession time.
+ *
+ * For a chain of withdraws and reinstates only, the output is what it was before
+ * `superseded` existed.
  */
 export function resolveLifecycleFromChain(views) {
     const chain = views
-        .filter((v) => LIFECYCLE_ATTESTATION_TYPES.includes(v.type))
+        .filter((v) => LIFECYCLE_CHAIN_ATTESTATION_TYPES.includes(v.type))
         .slice()
         .sort(compareLifecycleOrder);
-    const signerMatched = chain.filter((v) => v.signerMatchesTarget);
+    const signerMatched = chain.filter((v) => v.signerMatchesTarget && LIFECYCLE_STATUS_ATTESTATION_TYPES.includes(v.type));
     const latest = signerMatched[signerMatched.length - 1];
-    const status = latest && latest.type === ATTESTATION_WITHDRAWS ? 'withdrawn' : 'active';
+    const latestSupersede = [...signerMatched]
+        .reverse()
+        .find((v) => v.type === ATTESTATION_SUPERSEDES);
+    let status = 'active';
+    if (latest?.type === ATTESTATION_WITHDRAWS)
+        status = 'withdrawn';
+    else if (latest?.type === ATTESTATION_SUPERSEDES)
+        status = 'superseded';
+    // A reinstatement returns the node to where it stood before the withdrawal:
+    // superseded if a counting supersedes precedes it, which it does whenever one
+    // exists, since the reinstatement is the latest counting node.
+    else if (latest?.type === ATTESTATION_REINSTATES && latestSupersede)
+        status = 'superseded';
     const latestWithdraw = [...signerMatched]
         .reverse()
         .find((v) => v.type === ATTESTATION_WITHDRAWS);
@@ -86,13 +117,22 @@ export function resolveLifecycleFromChain(views) {
                 reinstatedReason: latestReinstate.reason,
             }
             : {}),
+        ...(latestSupersede
+            ? {
+                supersededAt: latestSupersede.createdAt,
+                ...(latestSupersede.successorNodeId
+                    ? { successorNodeId: latestSupersede.successorNodeId }
+                    : {}),
+            }
+            : {}),
     };
 }
 /**
  * Check #10 (legacy fallback) — derive lifecycle status from the pre-PR3
  * `withdrawnAt` / `reinstatedAt` columns (spec §8.10.4). Used when a content node
  * has no attestation envelopes. Withdrawn iff `withdrawnAt` is set and
- * `reinstatedAt` is not.
+ * `reinstatedAt` is not. It never derives `superseded`: the columns record no
+ * supersession.
  */
 export function resolveLifecycleFromLegacyColumns(columns) {
     if (!columns.withdrawnAt) {
@@ -114,6 +154,43 @@ export function resolveLifecycleFromLegacyColumns(columns) {
 function pickString(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
+function sameKey(a, b) {
+    try {
+        const x = extractRawPublicKey(a);
+        const y = extractRawPublicKey(b);
+        return x.length === y.length && x.every((byte, i) => byte === y[i]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a lifecycle attestation's signing key is bound to the signer it names.
+ *   - A key-derived identifier (`did:key:`) binds by derivation from `publicKey`,
+ *     under the rule check #14 applies to a record: it binds when #14 reads
+ *     `key_derived_match`.
+ *   - Any other identifier binds when `publicKey` is the target record's own
+ *     signing key, or when a registry fetched from its declared URL lists it
+ *     under that identifier: check #14 reads `ok` for the node's `kid`, and
+ *     check #5 reads the `(kid, publicKey)` pair as verified. The node carries
+ *     no verified signing time, so a deprecated key does not bind.
+ * A registry carried in a bundle, or one with no stated provenance, never binds.
+ */
+function isKeyBound(node, publicKey, kid, binding) {
+    const signer = node['signer'];
+    if (!signer || typeof signer !== 'object' || typeof signer.identifier !== 'string')
+        return false;
+    if (isKeyDerivedIdentifier(signer.identifier)) {
+        return checkSignerIdentity(node, kid, binding.registry, publicKey).status === 'key_derived_match';
+    }
+    if (binding.targetPublicKey && sameKey(publicKey, binding.targetPublicKey))
+        return true;
+    if (!kid || !binding.registry || binding.registryProvenance !== 'declared-url')
+        return false;
+    if (checkSignerIdentity(node, kid, binding.registry).status !== 'ok')
+        return false;
+    return verifyKeyTrust(publicKey, kid, undefined, binding.registry).verified;
+}
 /**
  * Resolve lifecycle (#10) INDEPENDENTLY from carried signed attestation nodes —
  * the browser/offline path that reaches `source: 'attestation-chain'` with no
@@ -127,12 +204,28 @@ function pickString(v) {
  *   - INTEGRITY: the recomputed envelope hash MUST equal the stored `nodeId`.
  *   - SIGNATURE: the Ed25519(ph) signature MUST verify over that hash.
  * A node failing any of these is EXCLUDED (a forged/tampered/misdirected transition
- * cannot move the status). Surviving nodes go to `resolveLifecycleFromChain`, which
- * applies the §8.10.3 retention asymmetry (a valid but non-signer-matched attestation
- * is surfaced in the chain yet does NOT move the publisher's status). That shared
- * resolver is unchanged, so the server route's output stays byte-identical.
+ * cannot move the status). A surviving node is signer-matched only when its
+ * `signer.identifier` equals the target's AND its signing key is bound to that
+ * identifier (`keyBound`), by what `binding` supplies:
+ *   - a key-derived identifier (`did:key:`) binds by derivation from the node's own
+ *     public key, the rule check #14 applies to a record;
+ *   - any other identifier binds by `binding.targetPublicKey` (the node is signed by
+ *     the target record's own key), or by `binding.registry` when
+ *     `binding.registryProvenance` is `declared-url` and it lists the node's
+ *     `(kid, publicKey)` under that identifier, read by the rules of checks #5 and
+ *     #14. A registry carried in a bundle, or with no stated provenance, never binds.
+ * Each view records `namesTarget` (the identifiers are equal) beside `keyBound`, so a
+ * reader can tell a third party's node from one that names the publisher under a key
+ * not bound to it.
+ * A surviving node that lacks a payload field §8.12.1 requires of its sub-type
+ * (§8.12.3; `ATTESTATION_REQUIRED_FIELDS`, absent, null or the empty string) is not
+ * signer-matched either, whoever signed it: it stays in the chain, names the fields
+ * in `missingFields`, and does not move the status.
+ * Surviving nodes go to `resolveLifecycleFromChain`, which applies the §8.10.3
+ * retention asymmetry (a valid but non-signer-matched attestation is surfaced in the
+ * chain yet does NOT move the publisher's status).
  */
-export function verifyLifecycleChain(carried, contentNodeId, targetSignerIdentifier) {
+export function verifyLifecycleChain(carried, contentNodeId, targetSignerIdentifier, binding = {}) {
     const views = [];
     for (const entry of carried) {
         // Reachability: the attestation must reference THIS content node.
@@ -144,20 +237,154 @@ export function verifyLifecycleChain(carried, contentNodeId, targetSignerIdentif
             continue;
         const signer = entry.node['signer'];
         const metadata = entry.node['metadata'];
+        const keyBound = isKeyBound(entry.node, entry.signature?.publicKey ?? '', pickString(entry.signature?.kid), binding);
+        const namesTarget = !!signer && signer.identifier === targetSignerIdentifier;
+        const type = pickString(entry.node['type']) ?? '';
+        const missingFields = missingRequiredFields(entry.node, type);
         views.push({
             nodeId: entry.nodeId,
-            type: pickString(entry.node['type']) ?? '',
+            type,
             signer,
             createdAt: pickString(metadata?.['createdAt']) ?? '',
             reason: pickString(entry.node['reason']),
             effectiveAt: pickString(entry.node['effectiveAt']),
             priorWithdrawalNodeId: pickString(entry.node['priorWithdrawalNodeId']),
+            successorNodeId: pickString(entry.node['successorNodeId']),
             signatureValid: verdict.signatureValid,
             nodeIdMatches: verdict.nodeIdMatches,
             hasTimestamp: !!entry.hasTimestamp,
             hasRekor: !!entry.hasRekor,
-            signerMatchesTarget: !!signer && signer.identifier === targetSignerIdentifier,
+            signerMatchesTarget: namesTarget && keyBound && missingFields.length === 0,
+            keyBound,
+            namesTarget,
+            missingFields,
         });
     }
     return resolveLifecycleFromChain(views);
 }
+/** The rule of each sub-type `checkAttestationNode` checks. `publishes`,
+ *  `locatedAt` and the specific-role-required sub-types have none here. */
+export const ATTESTATION_AUTHORIZATION_RULES = Object.freeze({
+    [ATTESTATION_WITHDRAWS]: 'publisher-only',
+    [ATTESTATION_REINSTATES]: 'publisher-only',
+    [ATTESTATION_SUPERSEDES]: 'publisher-only',
+    [ATTESTATION_REVISES]: 'publisher-only',
+    [ATTESTATION_CORROBORATES]: 'any-with-binding',
+    [ATTESTATION_CONTRADICTS]: 'any-with-binding',
+});
+/** Each checked sub-type's required payload fields (spec §8.12.1), beyond the
+ *  structural primitive. Optional fields (`effectiveAt`, a reinstatement's
+ *  `reason`, `reasoning`) are not listed. */
+export const ATTESTATION_REQUIRED_FIELDS = Object.freeze({
+    [ATTESTATION_WITHDRAWS]: ['targetNodeId', 'reason'],
+    [ATTESTATION_REINSTATES]: ['targetNodeId', 'priorWithdrawalNodeId'],
+    [ATTESTATION_SUPERSEDES]: ['targetNodeId', 'successorNodeId'],
+    [ATTESTATION_REVISES]: ['targetNodeId', 'successorNodeId'],
+    [ATTESTATION_CORROBORATES]: ['targetNodeId', 'scope'],
+    [ATTESTATION_CONTRADICTS]: ['targetNodeId', 'scope'],
+});
+/** The `signer.bindingTier` values an any-with-binding node may carry: the §8.5
+ *  graded identity ladder, and `platform` (spec §8.1.1). */
+export const BINDING_TIERS = ['pseudonymous', 'oauth', 'orcid', 'did-web', 'notarized', 'platform'];
+/**
+ * What `checkAttestationNode` reads for a node, first failure first:
+ *   - `node_id_mismatch` — the recomputed envelope hash is not the stored nodeId;
+ *   - `signature_invalid` — the signature does not verify over it;
+ *   - `unsigned` — the node carries no signature, so nothing can be bound;
+ *   - `not_checked` — publisher-only with no attested record supplied, or a
+ *     sub-type this check has no rule for;
+ *   - `other_signer` — publisher-only: the node names a signer other than the
+ *     attested record's, a third party's event;
+ *   - `publisher_key_unbound` — publisher-only: the node names the attested
+ *     record's signer, but its signing key is not bound to that signer;
+ *   - `key_unbound` — any-with-binding: the signing key is not bound to the signer
+ *     the node names;
+ *   - `binding_tier_off_ladder` — any-with-binding: `signer.bindingTier` is not in
+ *     `BINDING_TIERS`;
+ *   - `authorized` — the sub-type's rule holds.
+ */
+export const ATTESTATION_AUTHORIZATION_STATUSES = [
+    'authorized',
+    'not_checked',
+    'other_signer',
+    'publisher_key_unbound',
+    'key_unbound',
+    'binding_tier_off_ladder',
+    'unsigned',
+    'signature_invalid',
+    'node_id_mismatch',
+];
+function isAbsent(v) {
+    return v === undefined || v === null || v === '';
+}
+/** Each payload field §8.12.1 requires of `type` that `node` lacks, by name. */
+function missingRequiredFields(node, type) {
+    return (ATTESTATION_REQUIRED_FIELDS[type] ?? []).filter((f) => isAbsent(node[f]));
+}
+/**
+ * Check one `attestation/*` node on its own (spec §8.12.3), for `withdraws`,
+ * `reinstates`, `supersedes`, `revises`, `corroborates` and `contradicts`, in
+ * order:
+ *   1. integrity and signature, as `verifyAttestationNode` reads them;
+ *   2. the key binding, by the rule `verifyLifecycleChain` applies: a key-derived
+ *      identifier binds by derivation; any other identifier binds by a registry
+ *      fetched from its declared URL, and, for a publisher-only node only, by the
+ *      attested record's own signing key;
+ *   3. the sub-type's authorization rule:
+ *      - publisher-only (the four lifecycle sub-types) runs when `context.target`
+ *        is supplied, and otherwise reads `not_checked`. A node naming another
+ *        signer reads `other_signer`; one naming the target's signer under a key
+ *        not bound to it reads `publisher_key_unbound`;
+ *      - any-with-binding (`corroborates`, `contradicts`) needs the key bound and a
+ *        `signer.bindingTier` in `BINDING_TIERS`.
+ * It also names each required §8.12.1 payload field the node lacks. Pure; it moves
+ * no status: `resolveLifecycleFromChain` alone derives the lifecycle.
+ */
+export function checkAttestationNode(carried, context = {}) {
+    const node = carried.node;
+    const type = pickString(node['type']) ?? '';
+    const rule = ATTESTATION_AUTHORIZATION_RULES[type] ?? null;
+    const verdict = verifyAttestationNode(node, carried.nodeId, carried.signature ?? null);
+    const missingFields = missingRequiredFields(node, type);
+    const publicKey = carried.signature?.publicKey ?? '';
+    const signed = verdict.nodeIdMatches && verdict.signatureValid === true;
+    const keyBound = signed &&
+        isKeyBound(node, publicKey, pickString(carried.signature?.kid), {
+            ...(rule === 'publisher-only' && context.target ? { targetPublicKey: context.target.publicKey } : {}),
+            ...(context.registry ? { registry: context.registry } : {}),
+            ...(context.registryProvenance ? { registryProvenance: context.registryProvenance } : {}),
+        });
+    const result = (status) => ({
+        nodeId: verdict.nodeId,
+        type,
+        rule,
+        nodeIdMatches: verdict.nodeIdMatches,
+        signatureValid: verdict.signatureValid,
+        keyBound,
+        status,
+        missingFields,
+    });
+    if (!verdict.nodeIdMatches)
+        return result('node_id_mismatch');
+    if (verdict.signatureValid === false)
+        return result('signature_invalid');
+    if (verdict.signatureValid === null)
+        return result('unsigned');
+    if (rule === null)
+        return result('not_checked');
+    const signer = node['signer'];
+    const identifier = signer && typeof signer === 'object' ? signer.identifier : undefined;
+    if (rule === 'publisher-only') {
+        if (!context.target)
+            return result('not_checked');
+        if (identifier !== context.target.signerIdentifier)
+            return result('other_signer');
+        return result(keyBound ? 'authorized' : 'publisher_key_unbound');
+    }
+    if (!keyBound)
+        return result('key_unbound');
+    const tier = signer && typeof signer === 'object' ? signer.bindingTier : undefined;
+    if (!BINDING_TIERS.includes(tier))
+        return result('binding_tier_off_ladder');
+    return result('authorized');
+}

package/dist/verify.d.ts

@@ -39,13 +39,20 @@ export interface EnvelopeIntegrityResult {
     /** Present only when `status === 'unavailable'`. */
     reason?: ContentUnavailableReason;
 }
-/** Lifecycle STATE as carried by the WS1 sidecar (`CommitmentLifecycle`). */
+/** Lifecycle STATE as carried by the WS1 sidecar (`CommitmentLifecycle`). The
+ *  STATE path (`resolveLifecycleFromLegacyColumns`) reads only the withdrawal and
+ *  reinstatement columns, so a sidecar's `superseded` never reaches #10 without
+ *  the signed chain. */
 export interface CommitmentLifecycleState {
-    status: 'active' | 'withdrawn';
+    status: 'active' | 'withdrawn' | 'superseded';
     withdrawnAt?: string;
     withdrawnReason?: string;
     reinstatedAt?: string;
     reinstatedReason?: string;
+    /** When the record was superseded (the latest counting `supersedes`). */
+    supersededAt?: string;
+    /** The superseding record's nodeId. */
+    successorNodeId?: string;
 }
 /**
  * Everything `verifyRecord` needs, aligned to the WS1 commitment sidecar +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedstandards/verify-core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Portable, browser-safe verification core for Typed Standards record packages — the §9.2 check suite, single-sourced so it verifies identically on a server and in the browser.",
   "license": "MIT",
   "author": "Nathan Storey",