Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/one-delegation-chain-rule.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
'@adcp/sdk': minor
---

Align `authorizeDemandGrant` with the one delegation-chain rule (adcontextprotocol/adcp#8473, an erratum to ratified R6), and run its cross-SDK vectors.

- **Implicit authority:** `account.operator` and the signer's operator only need to each be the brand or its house. A brand-operated account with the house's own agent signing (or the reverse) is implicit; before, both had to equal the same domain.
- **Chains:** at most two grants from the house's record to the signer's operator, every grant covering the claim, with `account.operator` the brand, the house, or the first grant's grantee. Brand- and house-operated accounts can now use a two-grant chain, and the brand's own record can supply the second grant. When several candidate chains exist, an unreadable intermediary record is an outage only if no other chain authorizes.
- **Exclusivity:** `exclusive_grants: true` on the house's record makes `grants[]` the complete list whatever the scope, so an uncovered claim is `grant_absent` and `sellerAuthorization` is never called. This reverses the per-scope reading shipped in 16.5.0. Without it, an uncovered claim is at the seller's discretion, and a grant that does not cover the claim no longer narrows that discretion.

`test/lib/identity-3.3-delegation-chain-vectors.test.js` runs all 48 vectors from `static/test-vectors/delegation-chains.json` (vendored, pinned in `test/fixtures/delegation-chains/PINNED.json`).
93 changes: 51 additions & 42 deletions src/lib/identity-3.3/trust.ts
Original file line number Diff line number Diff line change
Expand Up @@ -408,10 +408,7 @@ export interface DemandGrantAuthorization {
export interface DemandGrantOptions {
evaluator: TrustEvaluator;
now?: () => number;
/**
* Only evaluated for uncovered claims, never fetch failures, and never for a scope an
* `exclusive_grants: true` record names in any grant.
*/
/** Only evaluated for uncovered claims against a record without `exclusive_grants: true`; never fetch failures. */
sellerAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;
/** Only for authoritative absence; never after a 200 or an exclusive record. */
legacyAuthorization?: (claim: DemandGrantClaim) => Promise<boolean>;
Expand All @@ -426,14 +423,19 @@ export interface DemandGrantOptions {
*/
resolveBrandHouse?: (brand: DemandGrantClaim['brand']) => Promise<{ domain: string; brand_id: string } | undefined>;
}
/** Candidate intermediary records fetched in parallel for one authorization. */
const INTERMEDIARY_FETCH_CONCURRENCY = 8;
function grantsScope(grant: TrustGrant, scope: string): boolean {
return grant.scopes.some(
granted => granted === '*' || granted === scope || (granted === 'adcp:all' && scope.startsWith('adcp:'))
);
}
function grantMatches(grant: TrustGrant, target: string, claim: DemandGrantClaim, now: number): boolean {
// Exact match on a registrable grantee: never reduce a host grantee to its eTLD+1.
if (registrableGrantee(grant.grantee) !== target) return false;
return registrableGrantee(grant.grantee) === target && grantCovers(grant, claim, now);
}
/** Every covering condition but the grantee: scope, agents[] narrowing, brands, countries and window. */
function grantCovers(grant: TrustGrant, claim: DemandGrantClaim, now: number): boolean {
if (!grantsScope(grant, claim.scope)) return false;
// An agents[] URL that does not parse lists no agent: the grant fails to
// match on its own and never throws out of the evaluation of other grants.
Expand Down Expand Up @@ -485,7 +487,6 @@ export async function authorizeDemandGrant(
: {}),
});
if (brand === operator && account === operator) return result('implicit', [brand]);
if (brand === operator && account !== operator) throw new IdentityAuthorizationError('grant_absent');
let house: { domain: string; brand_id: string } | undefined;
try {
house = await options.resolveBrandHouse?.(claim.brand);
Expand All @@ -502,9 +503,10 @@ export async function authorizeDemandGrant(
unavailable(cause);
}
const authoritativeBrand = house ? eTldPlusOne(house.domain) : brand;
// The house operating its own child brand: implicit. The signer's record,
// already matched above, is the house's record.
if (authoritativeBrand === operator && account === operator) return result('implicit', [brand, operator]);
// Implicit: account.operator and the signer's operator are each the brand or
// its house. The signer's record, already matched above, lists the agent.
const self = new Set([brand, authoritativeBrand]);
if (self.has(account) && self.has(operator)) return result('implicit', [...new Set([brand, account, operator])]);
const grantClaim = house ? { ...claim, brand: { ...claim.brand, brand_id: house.brand_id } } : claim;
// A grantor that once served a record and is now unreachable (404/410
// included) is an outage, never a grant removal or a legacy fallback.
Expand All @@ -513,42 +515,49 @@ export async function authorizeDemandGrant(
if (await options.legacyAuthorization?.(claim)) return result('legacy', [brand, account, operator]);
throw new IdentityAuthorizationError('grant_absent');
}
const first = (record.record.grants ?? []).filter(g => grantMatches(g, account, grantClaim, now));
if (account === operator && first.length) return result('trust', [brand, operator], [first[0]!]);
// A self-operated brand (brand is its own account.operator) may grant the
// signer's operator directly: account.operator is on the chain as the brand.
const selfOperated = account === brand || account === authoritativeBrand;
if (selfOperated && account !== operator) {
const direct = (record.record.grants ?? []).find(g => grantMatches(g, operator, grantClaim, now));
if (direct) return result('trust', [brand, operator], [direct]);
// The one delegation-chain rule (L2 Grants in trust records): at most two
// grants from the house's record to the signer's operator, every grant
// covering the claim, with account.operator the brand, its house, or the
// first grant's grantee.
const firsts: { grant: TrustGrant; grantee: string }[] = [];
for (const grant of record.record.grants ?? []) {
const grantee = registrableGrantee(grant.grantee);
if (grantee === undefined || !grantCovers(grant, grantClaim, now)) continue;
if (!self.has(account) && account !== grantee) continue;
if (grantee === operator) return result('trust', [brand, operator], [grant]);
firsts.push({ grant, grantee });
}
if (account !== operator && account !== brand && first.length) {
const intermediary = await options.evaluator.get(account);
if (intermediary.status === 'present') {
const second = (intermediary.record.grants ?? []).find(g => grantMatches(g, operator, grantClaim, now));
if (second) return result('trust', [brand, account, operator], [first[0]!, second]);
// Each distinct intermediary record is fetched once, at most
// INTERMEDIARY_FETCH_CONCURRENCY at a time, so N candidate chains cost about
// ceil(N / concurrency) fetch timeouts rather than N.
const grantees = [...new Set(firsts.map(f => f.grantee))];
const records = new Map<string, Awaited<ReturnType<TrustEvaluator['get']>> | { failed: unknown }>();
for (let i = 0; i < grantees.length; i += INTERMEDIARY_FETCH_CONCURRENCY) {
const batch = grantees.slice(i, i + INTERMEDIARY_FETCH_CONCURRENCY);
const settled = await Promise.allSettled(batch.map(grantee => options.evaluator.get(grantee)));
settled.forEach((outcome, j) =>
records.set(batch[j]!, outcome.status === 'fulfilled' ? outcome.value : { failed: outcome.reason })
);
}
let outage: unknown;
for (const { grant: first, grantee } of firsts) {
const intermediary = records.get(grantee)!;
if ('failed' in intermediary) {
// Another chain may still authorize; an unreadable link is an outage
// only if none does.
outage ??= intermediary.failed;
continue;
}
if (intermediary.status !== 'present') continue;
const second = (intermediary.record.grants ?? []).find(g => grantMatches(g, operator, grantClaim, now));
if (second) return result('trust', [brand, grantee, operator], [first, second]);
}
// A grant to account.operator (or, self-operated, to the signer's operator)
// for this scope that did not match is published narrowing: it blocks the
// seller's discretion. A grant whose grantee is not a registrable domain
// covers no claim, so it does not count here; its scopes still count for
// exclusive_grants.
const covered = (record.record.grants ?? []).some(g => {
const grantee = registrableGrantee(g.grantee);
return (
grantee !== undefined &&
(grantee === account || (selfOperated && grantee === operator)) &&
grantsScope(g, claim.scope)
);
});
// exclusive_grants makes grants[] exhaustive only for the scopes it names
// (any grant's scopes, registrable grantee or not). A scope no grant names,
// including every scope of a record with no grants, stays at the seller's
// discretion.
const exclusive =
record.record.exclusive_grants === true && (record.record.grants ?? []).some(g => grantsScope(g, claim.scope));
if (!covered && !exclusive && (await options.sellerAuthorization?.(claim)))
if (outage !== undefined) throw outage;
// L2 Absence: exclusive_grants on the authorizing record makes grants[] the
// complete list, whatever the scope. Without it, an uncovered claim is at
// the seller's discretion, and a grant that does not cover the claim never
// narrows that discretion. Only this (the house's) record's flag counts.
if (record.record.exclusive_grants !== true && (await options.sellerAuthorization?.(claim)))
return result('seller', [brand, account, operator]);
throw new IdentityAuthorizationError('grant_absent');
}
5 changes: 5 additions & 0 deletions test/fixtures/delegation-chains/PINNED.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"source": "adcontextprotocol/adcp#8473",
"sha": "3832036f8b2c153b7954992a2ffa06d1f5057898",
"path": "static/test-vectors/delegation-chains.json"
}
Loading
Loading