​

Migrating from 0.5 to 0.6

​

At a glance

​

Upgrade order

1. Upgrade verifiers first. Update the SDKs (or your own verifier) on every resource server so it accepts RS256 and ES256 and reads the standard claims. 0.6 SDKs read both claim forms.
2. Upgrade the auth service. Migrations apply on start. Defaults keep RS256 signing and keep issuing the legacy claim aliases, so 0.5 verifiers keep working.
3. Adopt the new features (purposes, object-form manifests, caps) one at a time. Each denies calls it cannot evaluate.
4. Before 0.7, move every resource server to the standard claims (0.6 SDKs already read them). Then set GRANT_TOKEN_LEGACY_CLAIMS=false (the 0.7 default). This changes only tokens issued from then on; tokens already issued keep their aliases until they expire. Switch to ES256, if you want it, only after step 1 is complete everywhere, following the rotation steps below.

​

Tool manifest schema 0.6

• an unknown key at any level;
• requires_decision: true on a read tool;
• four_eyes_on without requires_decision;
• empty caps, cost_units, allowed_purposes or four_eyes_on;
• a malformed purpose pattern, cap, unit or decision name.

• A tool that declares allowed_purposes is denied (purpose_not_allowed) unless the grant carries a matching purpose.
• A tool with requires_decision always returns decision_required, because decision grants are not accepted yet.
• A tool with caps or cost_units is denied with cap_exceeded / meter_unavailable unless the client has a caps meter.

​

Purpose-bound grants

• a purpose outside the vocabulary (aml.cdd.onboarding, aml.cdd.ongoing, aml.screening, procurement.vendor_onboarding, payments.payout) that is not a private x-<org>.<term>;
• a purpose sent without any tool:<connector>:<permission> scope.

• a claim that is not an array;
• an entry without a string type;
• a tools entry with an unknown key or a wrong type;
• two entries for one connector.

​

Spend caps

• Redis needs 6.0 or later and maxmemory-policy noeviction.
• Postgres needs the tables from SCHEMA_SQL / CAPS_SCHEMA_SQL or ensure_schema() / ensureSchema(), and a periodic prune().
• There is no automatic failover between backends.

• a wildcard key such as screen_*;
• an unknown window;
• a count outside 0–2147483647.

• A cap of 0 disables a tool.
• A per-case cap needs case_id / caseId (case_required).
• Units are reserved as the last check and are not refunded when the provider call fails. Use refund_unsent() / refundUnsent() only when the call was never sent.
• A tool with cost_units but no budget on the grant is allowed when a meter is configured.

​

ES256 signing

• names each key by its RFC 7638 thumbprint (grantex-rs256-…, grantex-es256-…), the same on every instance;
• verifies an RS256 token whose kid is any grantex-YYYY-MM, or that has no kid, with the legacy key — RSA_PRIVATE_KEY, or the key named by JWT_LEGACY_KID_KEY;
• also publishes the legacy key under grantex-YYYY-MM for the current month and the previous JWT_LEGACY_KID_MONTHS - 1 months (default 13 in total), so SDK verifiers that select keys by kid find it;
• keeps signing under the legacy kid for SIGNING_KEY_ACTIVATION_DELAY_SECONDS (default 900) after start, so resource servers holding a JWK Set fetched from a 0.5 instance keep accepting new tokens until they refresh it.

• an RS256 token whose kid names an EC key, and the reverse;
• a key published with a different alg;
• a key whose use is not sig;
• an ES256 key not on P-256;
• alg: none and HS256 (as before).

• an RSA key shorter than 2048 bits;
• an EC_PRIVATE_KEY that is not P-256;
• a key in the wrong setting (for example an RSA key in EC_PRIVATE_KEY);
• a JWT_VERIFICATION_PUBLIC_KEYS entry with private members, an unsupported alg, a legacy grantex-YYYY-MM kid, or a kid used by a different key;
• a JWT_LEGACY_KID_KEY that names no configured RSA key;
• with the postgres key store, a SIGNING_KEY_RETIRED_GRACE_SECONDS shorter than MAX_GRANT_LIFETIME_SECONDS (a warning when the latter is unset).

• Env key store.
  1. Publish the new public key in JWT_VERIFICATION_PUBLIC_KEYS, or set the other algorithm’s private key setting, and wait at least SIGNING_KEY_ACTIVATION_DELAY_SECONDS.
  2. Switch the private key, keeping the old public key in JWT_VERIFICATION_PUBLIC_KEYS (and JWT_LEGACY_KID_KEY for the old RSA key).
  3. Remove the old key only after its tokens have expired.
  The same key listed twice is one key, so an RSA-to-RSA rotation in one month raises no duplicate kid.
• Postgres key store. node dist/cli/rotate-signing-key.js [--alg ES256] publishes a pending key that signs only after SIGNING_KEY_ACTIVATION_DELAY_SECONDS. The previous key is then retired, its private key erased, and it stays published for SIGNING_KEY_RETIRED_GRACE_SECONDS. The legacy key stays published for the alias window.

• The env signing key becomes the stored active key, with the same kid.
• The other env keys are stored as retired public keys.
• The RSA key keeps its legacy kid marker.

​

Standard grant token claims

• 0.6: GRANT_TOKEN_LEGACY_CLAIMS defaults to true. The auth service issues the 0.5 aliases next to the standard claims, with identical values, so a 0.5 verifier keeps working.
• 0.7: the default becomes false, and tokens carry only the standard claims.
• A later release removes the flag.

1. Upgrade.
2. Watch for the deprecation warning. It means a token came from an issuer that is not yet on 0.6.
3. Set legacy_claims=False / legacyClaims: false / StandardClaimsOnly: true only when no warning has appeared for longer than your longest grant lifetime (so no pre-0.6 token can still be presented), and no grant with a whitespace scope remains (below). Until then keep the default: it accepts both forms.

const { payload } = await jwtVerify(token, jwks, {
  issuer, audience, algorithms: ['RS256', 'ES256'], typ: 'at+jwt',
  requiredClaims: ['iss', 'sub', 'aud', 'exp', 'iat', 'jti', 'client_id', 'scope'],
});
const scopes = (payload.scope as string).split(' ');
const grant = payload['urn:grantex:grant'] as { grant_id: string; agent_did: string };

if jwt.get_unverified_header(token).get("typ") != "at+jwt":
    raise jwt.InvalidTokenError("typ must be at+jwt")
payload = jwt.decode(token, key, algorithms=["RS256", "ES256"], issuer=issuer, audience=audience,
                     options={"require": ["iss", "sub", "aud", "exp", "iat", "jti"]})
scopes = payload["scope"].split(" ")
grant_id = payload["urn:grantex:grant"]["grant_id"]

• a standard claim and its alias disagree, for example scope and scp;
• act has no string sub or is nested more than 10 deep;
• urn:grantex:grant is not an object.

• urn:grantex:grant or any of its members;
• scope, scp, act, cnf, client_id, aud or authorization_details;
• a legacy alias.

• New grants. POST /v1/authorize refuses a scope containing whitespace with 400 INVALID_SCOPE. Action: use scope names without spaces.
• Existing grants. Grants created earlier with such a scope keep working: token exchange, refresh and delegation still issue tokens, and outstanding tokens verify. Because scope is space-delimited and cannot hold such a scope, these tokens omit scope and always carry scp, whatever GRANT_TOKEN_LEGACY_CLAIMS says. A verifier reading standard claims only (legacy_claims=False, and the 0.7 default) refuses them rather than read a different scope set. Action: re-issue such grants with space-free scopes before switching verifiers to standard-only.
• Other entry points. Agent registration and consent bundles still accept such scopes (FINDINGS G-11).

​

Database migrations

​

New settings

​

Checklist

• Every resource server verifies with a 0.6 SDK or allows RS256 and ES256 with kid-based key selection.
• Manifest files load with the 0.6 SDK: no duplicate keys, no tool named cost_units.
• Object-form declarations are paired with purposes on grants, a caps meter, or an accepted decision_required.
• Clients that push authorization_details send well-formed entries.
• The auth service starts with the configured signing keys; the RSA key that signed pre-0.6 tokens stays configured (or is named by JWT_LEGACY_KID_KEY) until those tokens expire.
• Key rotations publish the new key first and keep the old key until its tokens expire.
• No grant with a whitespace scope remains before verifiers read standard claims only.
• No deprecation warning for legacy claims appears on any resource server.
• Custom verifiers read scope, client_id, act and urn:grantex:grant.
• GRANT_TOKEN_LEGACY_CLAIMS=false is planned before 0.7, after every resource server reads the standard claims.