Authorization & Consent Recording

[Entity: alice (human)]
  └── grants ──► [Authorization action]
                   ├── scope: "read:provenance, write:provenance"
                   ├── target: "project:my-app"
                   ├── expiresAt: "2026-12-31"
                   └── produces ──► [Resource: consent-record (CID: bafybei...)]

import { ProvenanceKit } from "@provenancekit/sdk";

const pk = new ProvenanceKit({ apiKey: "pk_live_..." });

// 1. Record that a user granted consent/authorization
const consentRecord = await pk.file(
  Buffer.from(JSON.stringify({
    subject: "user:alice",
    scope: ["read:content", "write:content", "ai:generate"],
    grantedAt: new Date().toISOString(),
    expiresAt: "2026-12-31T23:59:59Z",
    purpose: "AI-assisted content generation for personal blog",
    withdrawable: true,
  })),
  {
    entity: { id: "user:alice", role: "human", name: "Alice" },
    action: {
      type: "verify",     // "verify" = an assertion/decision action in EAA
      extensions: {
        "ext:authorization@1.0.0": {
          grantedTo: "app:content-generator",
          scope: ["read:content", "write:content", "ai:generate"],
          expiresAt: "2026-12-31T23:59:59Z",
          purpose: "AI-assisted content generation",
          consentVersion: "1.2",
          withdrawable: true,
        },
      },
    },
    resourceType: "text",
  }
);
// consentRecord.cid = the CID of the consent document itself

// 2. Later: perform an AI action, referencing the consent that authorized it
const { cid: outputCid } = await pk.file(
  Buffer.from(aiGeneratedContent),
  {
    entity: { id: "app:content-generator", role: "organization" },
    action: {
      type: "create",
      inputCids: [consentRecord.cid],    // Consent is an input to the action
      extensions: {
        "ext:ai@1.0.0": {
          provider: "anthropic",
          model: "claude-sonnet-4-6",
          autonomyLevel: "assistive",
        },
        "ext:authorization@1.0.0": {
          authorizedBy: "user:alice",
          consentCid: consentRecord.cid,  // Explicit back-reference
          scope: ["ai:generate"],
          verifiedAt: new Date().toISOString(),
        },
      },
    },
    resourceType: "text",
  }
);

// The graph: alice-grants-consent → consent-cid ← ai-action → output

alice (entity: human)
  └── verify ──► consent.json (resource: text, CID: bafybei...)
                   ├── ext:authorization@1.0.0:
                   │     grantedTo: "app:content-generator"
                   │     scope: ["read:content", "write:content", "ai:generate"]
                   │     expiresAt: "2026-12-31"
                   │     purpose: "AI-assisted content generation"
                   └── used as input to ──►
                                           action: create
                                             ├── performedBy: content-generator
                                             ├── ext:ai@1.0.0: { model: claude-sonnet-4-6 }
                                             ├── ext:authorization@1.0.0: { consentCid: bafybei... }
                                             └── produces ──► output.txt (CID: bafybej...)

import { ProvenanceKit } from "@provenancekit/sdk";

async function checkAuthorization(
  entityId: string,
  requiredScope: string[]
): Promise<boolean> {
  const pk = new ProvenanceKit({ apiKey: process.env.PK_API_KEY! });

  // Search for recent consent records from this entity
  const results = await pk.searchText(`authorization consent ${entityId}`, {
    topK: 10,
    type: "text",
  });

  for (const result of results) {
    const bundle = await pk.bundle(result.cid);
    const action = bundle.actions?.find(
      a => a.extensions?.["ext:authorization@1.0.0"]
    );
    const authExt = action?.extensions?.["ext:authorization@1.0.0"] as any;

    if (!authExt) continue;

    // Check scope
    const hasScope = requiredScope.every(s => authExt.scope?.includes(s));
    if (!hasScope) continue;

    // Check expiry
    if (authExt.expiresAt && new Date(authExt.expiresAt) < new Date()) continue;

    return true;
  }

  return false;
}

// Use before processing
const authorized = await checkAuthorization("user:alice", ["ai:generate"]);
if (!authorized) throw new Error("User has not granted required consent");

// Record that consent was withdrawn
const withdrawalRecord = await pk.file(
  Buffer.from(JSON.stringify({
    withdraws: consentRecord.cid,
    withdrawnAt: new Date().toISOString(),
    reason: "User opted out via privacy settings",
  })),
  {
    entity: { id: "user:alice", role: "human" },
    action: {
      type: "verify",
      inputCids: [consentRecord.cid],   // Points to the consent being withdrawn
      extensions: {
        "ext:authorization@1.0.0": {
          action: "withdraw",
          withdrawsCid: consentRecord.cid,
          withdrawnAt: new Date().toISOString(),
        },
      },
    },
    resourceType: "text",
  }
);
// The graph now shows: original consent → withdrawal
// Any system checking authorization must walk the graph and check for withdrawals

// Step 1: AI generates a draft (autonomyLevel: supervised)
const draft = await pk.file(aiDraftBuffer, {
  entity: { id: "app:ai-writer", role: "organization" },
  action: {
    type: "create",
    extensions: {
      "ext:ai@1.0.0": {
        provider: "openai",
        model: "gpt-4o",
        autonomyLevel: "supervised",  // Human review required
      },
    },
  },
});

// Step 2: Human reviews and approves — records the approval
const approval = await pk.file(
  Buffer.from(JSON.stringify({ approved: true, notes: "Good. Publish it." })),
  {
    entity: { id: "user:editor", role: "human", name: "Editor" },
    action: {
      type: "verify",
      inputCids: [draft.cid],     // References the draft being approved
      extensions: {
        "ext:authorization@1.0.0": {
          action: "approve",
          approvedCid: draft.cid,
          approvedAt: new Date().toISOString(),
          approvedBy: "user:editor",
        },
      },
    },
    resourceType: "text",
  }
);

// Step 3: Publish — references both draft and approval
const published = await pk.file(finalBuffer, {
  entity: { id: "app:publishing-system", role: "organization" },
  action: {
    type: "transform",
    inputCids: [draft.cid, approval.cid],  // Both draft + approval are inputs
  },
  resourceType: "text",
});

// Graph: ai-generates-draft → editor-approves → publishing-system-publishes

const graph = await pk.graph(outputCid, 10);

// Find all authorization events in the lineage
const authActions = graph.nodes.filter(n =>
  n.type === "action" &&
  n.data?.extensions?.["ext:authorization@1.0.0"]
);

authActions.forEach(a => {
  const auth = a.data.extensions["ext:authorization@1.0.0"];
  console.log("Authorization:", {
    action: auth.action ?? "grant",
    grantedTo: auth.grantedTo,
    scope: auth.scope,
    expiresAt: auth.expiresAt,
    withdrawsCid: auth.withdrawsCid,
  });
});

// Check for withdrawals
const withdrawals = authActions.filter(
  a => a.data.extensions["ext:authorization@1.0.0"]?.action === "withdraw"
);

if (withdrawals.length > 0) {
  console.warn("Consent has been withdrawn — stop processing");
}