@orangecheck/agent-core 2.2.0 → 2.4.0

package/src/federation.ts

@@ -25,7 +25,13 @@ import {
     hexEncode,
     revocationCanonicalMessage,
 } from './canonical.js';
-import type { ActorRef, AgentErrorCode, DelegationBond, DelegationRevocationRef } from './types.js';
+import type {
+    ActorRef,
+    AgentErrorCode,
+    DelegationBond,
+    DelegationRevocationRef,
+    RevocationEnvelope,
+} from './types.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (FEDERATION.md §2 / §3.2)
@@ -221,6 +227,13 @@ async function checkFederationQuorum(
 
 export interface VerifyFederationDelegationInput extends VerifyFederationBase {
     envelope: FederationDelegationEnvelope;
+    /**
+     * Revocations to check (kind-30085 by `#delegation`): federation revocations,
+     * and agent self-revocations when `revocation.holders` includes "agent".
+     * Required unless `skipRevocationCheck` states that revocation is not checked.
+     */
+    revocations?: Array<FederationRevocationEnvelope | RevocationEnvelope>;
+    skipRevocationCheck?: boolean;
     now?: Date;
     skipTemporalCheck?: boolean;
 }
@@ -273,6 +286,21 @@ export async function verifyFederationDelegation(
     const quorum = await checkFederationQuorum(env.principal, env.sig, env.id, input);
     if (!quorum.ok) return quorum;
 
+    // Revocation — the same rule as verifyDelegation: check unless told not to.
+    if (!input.skipRevocationCheck && !input.revocations) {
+        return fail(
+            'E_MALFORMED',
+            'verifyFederationDelegation requires `revocations` (fetch kind-30085 by #delegation) ' +
+                'or an explicit skipRevocationCheck:true to state that revocation is not being checked'
+        );
+    }
+    for (const rev of input.revocations ?? []) {
+        if (rev?.delegation_id !== env.id) continue;
+        const rr = await verifyRevocationOf(env, rev, input);
+        if (!rr.ok) continue; // a malformed or unauthorized revocation revokes nothing
+        return fail('E_REVOKED', `delegation ${env.id} was revoked by ${rev.id}`);
+    }
+
     if (!input.skipTemporalCheck) {
         const now = input.now ?? new Date();
         const issued = new Date(env.issued_at);
@@ -285,6 +313,52 @@ export async function verifyFederationDelegation(
     return { ok: true, id: env.id, canonicalMessage: delegationCanonicalMessage(canonInput) };
 }
 
+/**
+ * FEDERATION.md §4: the federation (M-of-N) may always revoke; the agent may
+ * self-revoke with its own BIP-322 signature when `revocation.holders`
+ * includes "agent".
+ */
+async function verifyRevocationOf(
+    d: FederationDelegationEnvelope,
+    rev: FederationRevocationEnvelope | RevocationEnvelope,
+    input: VerifyFederationBase
+): Promise<FederationVerifyResult> {
+    if ((rev.signer as FederationPrincipal | undefined)?.alg === 'federation') {
+        return verifyFederationRevocation({
+            envelope: rev as FederationRevocationEnvelope,
+            delegation: d,
+            verifyBip322: input.verifyBip322,
+            skipSignatureVerification: input.skipSignatureVerification,
+        });
+    }
+    const v1 = rev as RevocationEnvelope;
+    const holders = d.revocation?.holders ?? ['principal'];
+    if (!Array.isArray(holders) || !holders.includes('agent')) {
+        return fail('E_REVOKER_UNAUTHORIZED', 'only the federation may revoke this delegation');
+    }
+    if (v1.kind !== 'agent-revocation' || v1.signer?.address !== d.agent.address) {
+        return fail('E_REVOKER_UNAUTHORIZED', 'a single-address revocation must be signed by the agent');
+    }
+    if (typeof v1.reason !== 'string' || !ISO_UTC.test(v1.signed_at ?? '')) {
+        return fail('E_MALFORMED', 'revocation reason / signed_at invalid');
+    }
+    const canonInput = {
+        address: v1.signer.address,
+        delegation_id: v1.delegation_id,
+        reason: v1.reason,
+        signed_at: v1.signed_at,
+    };
+    const id = computeRevocationId(canonInput);
+    if (id !== v1.id) return fail('E_BAD_ID', `reconstructed id (${id}) != revocation.id (${v1.id})`);
+    if (!input.skipSignatureVerification) {
+        if (!input.verifyBip322) return fail('E_BAD_SIG', 'no BIP-322 verifier supplied');
+        if (typeof v1.sig?.value !== 'string' || !(await input.verifyBip322(v1.id, v1.sig.value, v1.signer.address))) {
+            return fail('E_BAD_SIG', 'revocation BIP-322 signature did not verify');
+        }
+    }
+    return { ok: true, id: v1.id, canonicalMessage: revocationCanonicalMessage(canonInput) };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Revocation under a federation principal (FEDERATION.md §4)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/revocation-authority.test.ts

@@ -176,13 +176,37 @@ describe('revocation priority uses only verified anchors', () => {
             verifyOtsAnchor: async () => false,
         });
         expect(clean.ok && clean.anchor).toEqual({
-            status: 'confirmed',
+            status: 'claimed',
             blockHeight: 1,
             blockHash: 'ab'.repeat(32),
             verified: false,
         });
     });
 
+    // The ots block is outside the signature: its block is a claim until walked.
+    it('reports an unwalked anchor as claimed, and a walked one as confirmed', async () => {
+        const unwalked = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [],
+            skipSignatureVerification: true,
+        });
+        expect(unwalked.ok && unwalked.anchor.status).toBe('claimed');
+        const walked = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => true,
+        });
+        expect(walked.ok && walked.anchor).toEqual({
+            status: 'confirmed',
+            blockHeight: 1,
+            blockHash: 'ab'.repeat(32),
+            verified: true,
+        });
+    });
+
     it('the anchor verifier is asked about the envelope it belongs to', async () => {
         const a = action(d, later, confirmed(100));
         const revAnchored = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(200));

package/src/scope.test.ts

@@ -204,3 +204,28 @@ describe('ordered-op values must be decimal integers (SPEC §7.4)', () => {
         expect(isSubScope(exercised, parseScope('ln:send(max_sats<=0)'))).toBe(false);
     });
 });
+
+// oc-pledge-protocol SPEC §7.3 defines pledge:create and its constraint keys.
+describe('pledge:create is a registered scope', () => {
+    for (const s of [
+        'pledge:create',
+        'pledge:create(max_bond_sats=2000000)',
+        'pledge:create(mechanism=vote_resolves)',
+        'pledge:create(counterparty=bc1qalice000000000000000000000000000000000)',
+        'pledge:create(max_bond_sats=2000000,mechanism=vote_resolves,counterparty=bc1qalice000000000000000000000000000000000)',
+    ]) {
+        it(`strict mode accepts ${s}`, () => {
+            expect(() => validateScope(parseScope(s), { mode: 'strict' })).not.toThrow();
+        });
+    }
+
+    it('strict mode still rejects an unregistered pledge:create key', () => {
+        expect(() => validateScope(parseScope('pledge:create(foo=1)'), { mode: 'strict' })).toThrow(ScopeParseError);
+    });
+
+    it('max_bond_sats is an ordered numeric bound', () => {
+        const granted = parseScope('pledge:create(max_bond_sats<=2000000)');
+        expect(isSubScope(parseScope('pledge:create(max_bond_sats=500000)'), granted)).toBe(true);
+        expect(isSubScope(parseScope('pledge:create(max_bond_sats=3000000)'), granted)).toBe(false);
+    });
+});

package/src/scope.ts

@@ -34,6 +34,8 @@ export const REGISTERED_SCOPES: Record<string, { keys: string[] }> = {
     'http:request': { keys: ['origin', 'method', 'max_rps', 'max_bytes_out'] },
     'ln:send': { keys: ['max_sats', 'node', 'max_fee_sats'] },
     'mcp:invoke': { keys: ['server', 'tool', 'max_invocations'] },
+    // oc-pledge-protocol SPEC §7.3.
+    'pledge:create': { keys: ['max_bond_sats', 'mechanism', 'counterparty'] },
 };
 
 /** Keys whose values are compared numerically for sub-scope ordering. */
@@ -46,6 +48,7 @@ const NUMERIC_KEYS = new Set<string>([
     'max_sats',
     'max_fee_sats',
     'max_invocations',
+    'max_bond_sats',
     'kind',
 ]);
 

package/src/types.ts

@@ -289,10 +289,15 @@ export interface VerifyActionOkExtra {
      */
     chain: SubdelegationEnvelope[];
     scopeExercised: string;
+    /**
+     * `claimed` is a confirmed `ots` block no verifier walked: the block is the
+     * envelope's say-so. Only a passing `verifyOtsAnchor` yields `confirmed`.
+     */
     anchor:
         | { status: 'none' }
         | { status: 'pending' }
-        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };
+        | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }
+        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };
 }
 
 export type VerifyActionResult =

package/src/verify.ts

@@ -512,8 +512,11 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         if (h === null || hash === null) {
             return err('E_MALFORMED', 'confirmed OTS proof missing block_height or block_hash');
         }
-        const verified = actionAnchor !== null;
-        anchor = { status: 'confirmed', blockHeight: h, blockHash: hash, verified } as typeof anchor;
+        anchor = (
+            actionAnchor !== null
+                ? { status: 'confirmed', blockHeight: h, blockHash: hash, verified: true }
+                : { status: 'claimed', blockHeight: h, blockHash: hash, verified: false }
+        ) as typeof anchor;
     }
 
     return {