@kubun/credential 0.17.4 → 0.18.0

package/lib/op.js

@@ -1,304 +0,0 @@
-import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
-import { toB64U } from '@sozai/codec';
-import { credentialEntryDigest, credentialKeyDigest, credentialWrappingDigest, digestParts } from './digest.js';
-/** The digest of the bytes a row holds, per subject kind. */ export function credentialRowDigest(subject) {
-    switch(subject.kind){
-        case 'key':
-            return credentialKeyDigest({
-                ownerDID: subject.row.owner_did,
-                suite: subject.row.suite,
-                version: subject.row.version,
-                state: subject.row.state
-            });
-        case 'wrapping':
-            return credentialWrappingDigest({
-                wrappingID: subject.row.wrapping_id,
-                recipientDID: subject.row.recipient_did,
-                iv: toB64U(new Uint8Array(subject.row.iv)),
-                wrappedKey: toB64U(new Uint8Array(subject.row.wrapped_key)),
-                factors: subject.row.factors
-            });
-        case 'entry':
-            return credentialEntryDigest({
-                entryID: subject.row.entry_id,
-                iv: toB64U(new Uint8Array(subject.row.iv)),
-                ciphertext: toB64U(new Uint8Array(subject.row.ciphertext)),
-                hlc: subject.row.hlc
-            });
-    }
-}
-/** The digest of the bytes a row is about to be written with, per subject kind. */ export function credentialPutDigest(subject) {
-    switch(subject.kind){
-        case 'key':
-            return credentialKeyDigest({
-                ownerDID: subject.params.ownerDID,
-                suite: subject.params.suite,
-                version: subject.params.version,
-                state: subject.params.state
-            });
-        case 'wrapping':
-            return credentialWrappingDigest({
-                wrappingID: subject.params.wrappingID,
-                // An omitted recipient and an explicit null are the same wrapping, as
-                // the signer folds them.
-                recipientDID: subject.params.recipientDID ?? null,
-                iv: toB64U(subject.params.iv),
-                wrappedKey: toB64U(subject.params.wrappedKey),
-                factors: subject.params.factors
-            });
-        case 'entry':
-            return credentialEntryDigest({
-                entryID: subject.params.entryID,
-                iv: toB64U(subject.params.iv),
-                ciphertext: toB64U(subject.params.ciphertext),
-                hlc: subject.params.hlc
-            });
-    }
-}
-/**
- * Whether a verified claim speaks for exactly these bytes under exactly this
- * identity.
- *
- * The identifiers are checked along with the digest: a claim over another row's
- * content would otherwise authenticate this one as soon as the two held the same
- * bytes, which two wrappings of the same key routinely do not but two
- * empty-state keys would. `keyID` matters beyond that — it is the column the
- * sync lane buckets a vault by, so an op filed under another key's id would
- * travel with the wrong set.
- *
- * `stamp` is the row's own `hlc` where the row has one, which is entries only.
- * It has to equal the claim's: the op row keeps the claim's stamp and the entry
- * row keeps its own, and the two disagreeing would order a row differently from
- * the op that speaks for it.
- */ function matchesClaim(claim, subject, contentDigest) {
-    return claim.subjectKind === subject.kind && claim.subjectID === subject.subjectID && claim.keyID === subject.keyID && claim.keyVersion === subject.keyVersion && (subject.stamp == null || claim.hlc === subject.stamp) && !claim.deleted && claim.contentDigest === contentDigest;
-}
-/** Whether a verified claim speaks for a stored row. */ export function credentialOpMatchesRow(claim, subject) {
-    const identity = subject.kind === 'key' ? {
-        kind: 'key',
-        subjectID: subject.row.key_id,
-        keyID: subject.row.key_id,
-        keyVersion: subject.row.version
-    } : subject.kind === 'wrapping' ? {
-        kind: 'wrapping',
-        subjectID: subject.row.wrapping_id,
-        keyID: subject.row.key_id,
-        keyVersion: subject.row.key_version
-    } : {
-        kind: 'entry',
-        subjectID: subject.row.entry_id,
-        keyID: subject.row.key_id,
-        keyVersion: subject.row.key_version,
-        stamp: subject.row.hlc
-    };
-    return matchesClaim(claim, identity, credentialRowDigest(subject));
-}
-/** Whether a verified claim speaks for a row about to be written. */ export function credentialOpMatchesPut(claim, subject) {
-    const identity = subject.kind === 'key' ? {
-        kind: 'key',
-        subjectID: subject.params.keyID,
-        keyID: subject.params.keyID,
-        keyVersion: subject.params.version
-    } : subject.kind === 'wrapping' ? {
-        kind: 'wrapping',
-        subjectID: subject.params.wrappingID,
-        keyID: subject.params.keyID,
-        keyVersion: subject.params.keyVersion
-    } : {
-        kind: 'entry',
-        subjectID: subject.params.entryID,
-        keyID: subject.params.keyID,
-        keyVersion: subject.params.keyVersion,
-        stamp: subject.params.hlc
-    };
-    return matchesClaim(claim, identity, credentialPutDigest(subject));
-}
-async function signOp(identity, claim) {
-    const signed = await identity.signToken({
-        ...claim
-    }, {
-        embedLongForm: true
-    });
-    const opJWT = stringifyToken(signed);
-    return {
-        keyID: claim.keyID,
-        // Normalized, unlike a wrapping's recipient: this one is compared against a
-        // key's owner and against a verified issuer, never resolved to a document.
-        authorDID: normalizeDID(identity.id),
-        hlc: claim.hlc,
-        opJWT,
-        // The token addresses itself, the way the graph mutation log addresses a
-        // mutation by its hash.
-        opHash: digestParts([
-            opJWT
-        ]),
-        // A wrapping or entry mirrors the branch it signed; anything without one
-        // gets the empty label. A key-op overrides this from its own `opHash`.
-        branchID: claim.branchID ?? ''
-    };
-}
-export function createCredentialOpSigner(identity) {
-    async function tombstone(subject, hlc) {
-        return await signOp(identity, {
-            subjectKind: subject.subjectKind,
-            subjectID: subject.subjectID,
-            keyID: subject.keyID,
-            keyVersion: subject.keyVersion,
-            hlc,
-            contentDigest: null,
-            deleted: true
-        });
-    }
-    return {
-        async key (params, hlc) {
-            const input = await signOp(identity, {
-                subjectKind: 'key',
-                subjectID: params.keyID,
-                keyID: params.keyID,
-                keyVersion: params.version,
-                hlc,
-                contentDigest: credentialKeyDigest({
-                    ownerDID: params.ownerDID,
-                    suite: params.suite,
-                    version: params.version,
-                    state: params.state
-                }),
-                deleted: false
-            });
-            // The key-op labels its own branch. It cannot claim this in the signed
-            // token — the label folds `opHash`, which the signature produces — so it
-            // rides on the input and a receiver recomputes it from the op's `hlc` and
-            // `opHash`, which is what authenticates it.
-            return {
-                ...input,
-                branchID: `${hlc}:${input.opHash}`
-            };
-        },
-        async wrapping (params, hlc, branchID) {
-            return await signOp(identity, {
-                subjectKind: 'wrapping',
-                subjectID: params.wrappingID,
-                keyID: params.keyID,
-                keyVersion: params.keyVersion,
-                hlc,
-                contentDigest: credentialWrappingDigest({
-                    wrappingID: params.wrappingID,
-                    // An omitted recipient and an explicit null are the same wrapping, and
-                    // the stored row keeps only one of the two spellings.
-                    recipientDID: params.recipientDID ?? null,
-                    iv: toB64U(params.iv),
-                    wrappedKey: toB64U(params.wrappedKey),
-                    factors: params.factors
-                }),
-                deleted: false,
-                branchID
-            });
-        },
-        async entry (params, branchID) {
-            return await signOp(identity, {
-                subjectKind: 'entry',
-                subjectID: params.entryID,
-                keyID: params.keyID,
-                keyVersion: params.keyVersion,
-                hlc: params.hlc,
-                contentDigest: credentialEntryDigest({
-                    entryID: params.entryID,
-                    iv: toB64U(params.iv),
-                    ciphertext: toB64U(params.ciphertext),
-                    hlc: params.hlc
-                }),
-                deleted: false,
-                branchID
-            });
-        },
-        tombstone,
-        async wrappingTombstone (subject, hlc) {
-            return {
-                ...await tombstone(subject, hlc),
-                subjectID: subject.subjectID
-            };
-        }
-    };
-}
-function isSubjectKind(value) {
-    return value === 'key' || value === 'wrapping' || value === 'entry';
-}
-/**
- * Split a `branchID` into its `hlc` and `opHash` halves.
- *
- * The label is `${hlc}:${opHash}`, and both halves — an HLC and a DID nodeID —
- * carry their own colons, but `opHash` is base64url and carries none, so the
- * LAST colon is the boundary however many precede it.
- */ function splitBranchID(branchID) {
-    const boundary = branchID.lastIndexOf(':');
-    return boundary < 0 ? {
-        hlc: branchID,
-        opHash: ''
-    } : {
-        hlc: branchID.slice(0, boundary),
-        opHash: branchID.slice(boundary + 1)
-    };
-}
-/**
- * Order two branch labels, keyless and total.
- *
- * The `hlc` halves are compared as strings: the serialized HLC form is
- * lexically total-ordered by construction (fixed-width ISO wall time, then a
- * zero-padded counter, then the nodeID), the same property the store's
- * tombstone check leans on. Two concurrent rotations neither dominate, so the
- * `opHash` breaks the tie — also lexical, and distinct per op, which is what
- * makes the order total and identical on every device.
- */ export function compareBranchIDs(a, b) {
-    const left = splitBranchID(a);
-    const right = splitBranchID(b);
-    if (left.hlc !== right.hlc) {
-        return left.hlc < right.hlc ? -1 : 1;
-    }
-    return left.opHash < right.opHash ? -1 : left.opHash > right.opHash ? 1 : 0;
-}
-/**
- * The single branch a keyless party names as the winner: the one whose
- * introducing key-op dominates by HLC, `opHash` breaking genuine concurrency.
- * Order-independent — every device folds the same set to the same label.
- */ export function selectWinningBranch(branchIDs) {
-    if (branchIDs.length === 0) {
-        throw new RangeError('selectWinningBranch requires at least one branchID');
-    }
-    return branchIDs.reduce((winner, candidate)=>compareBranchIDs(candidate, winner) > 0 ? candidate : winner);
-}
-/**
- * Verify an op and extract its claim. Returns `null` (never throws) when the
- * token is unparseable, unsigned (`alg: 'none'`), or structurally malformed — an
- * attacker cannot forge an `iss` this way.
- */ export async function verifyCredentialOp(token) {
-    let verified;
-    try {
-        verified = await verifyToken(token);
-    } catch  {
-        return null;
-    }
-    if (!isVerifiedToken(verified)) {
-        return null;
-    }
-    const { iss, subjectKind, subjectID, keyID, keyVersion, hlc, contentDigest, deleted, branchID } = verified.payload;
-    if (!isSubjectKind(subjectKind) || typeof subjectID !== 'string' || typeof keyID !== 'string' || typeof keyVersion !== 'number' || typeof hlc !== 'string' || typeof deleted !== 'boolean' || // A live op with no digest would authenticate any bytes at all, so the two
-    // fields are checked against each other rather than one at a time.
-    (deleted ? contentDigest !== null : typeof contentDigest !== 'string') || // Optional — a key-op omits it — but a present one must be the signed string
-    // a receiver reads as the row's branch label.
-    branchID != null && typeof branchID !== 'string') {
-        return null;
-    }
-    return {
-        issuer: normalizeDID(iss),
-        claim: {
-            subjectKind,
-            subjectID,
-            keyID,
-            keyVersion,
-            hlc,
-            contentDigest: contentDigest,
-            deleted,
-            branchID: branchID
-        }
-    };
-}