Designing PIC-X: Exposing Configuration through .well-known/pic-x-configuration

PIC-X exposes discovery at two levels: a server control-plane document and a per-realm PIC-X discovery document.

The server is not an issuer. A realm is an isolated trust domain and issuer boundary. Realm discovery publishes issuer-scoped endpoints, keys, token-exchange metadata, and PIC authority and continuity capabilities.

/.well-known/server-configuration
        |
        +--> realm: acme
                |
                v
/realms/acme/.well-known/pic-x-configuration

Discovery Model

The server-level document describes the PIC-X instance. The realm-level document describes the issuer clients use for PIC exchange and verification.

A deployment may enumerate public realms from server discovery, but enumeration is not required. A client that already knows a realm path may begin directly at the realm discovery endpoint.

/realms/acme/.well-known/pic-x-configuration
      |
      +--> token_endpoint
      +--> jwks_uri
      +--> pic_context_of_authority
      +--> pic_continuity_proposals
      +--> pic_continuity_transition
      +--> pic_continuity
      +--> pic_token

Each realm owns its issuer identity, signing keys, audit trail, token lifecycle, and PIC trust semantics.

Server-Level Discovery

/.well-known/server-configuration

The server-level document is control-plane metadata.

The exact server-configuration JSON schema is outside the scope of this article.

Realm-Level Discovery

For realm acme, PIC-X discovery is exposed at:

/realms/acme/.well-known/pic-x-configuration

The realm document contains issuer-scoped endpoints, keys, token-exchange metadata, attestation and trusted-anchor endpoints, and PIC-specific capabilities.

Realm Discovery JSON

The following realm discovery JSON is canonical for this article:

{
  "issuer": "http://127.0.0.1:5556/realms/acme",
  "profile": "https://pic-protocol.org/profiles/0.2",

  "token_endpoint": "http://127.0.0.1:5556/realms/acme/token",
  "revocation_endpoint": "http://127.0.0.1:5556/realms/acme/revoke",
  "jwks_uri": "http://127.0.0.1:5556/realms/acme/keys",

  "attestations_endpoint": "http://127.0.0.1:5556/realms/acme/attestations",
  "trust_anchors_endpoint": "http://127.0.0.1:5556/realms/acme/trust-anchors",

  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:token-exchange"
  ],

  "subject_token_types_supported": [
    "urn:ietf:params:oauth:token-type:access_token",
    "https://pic-protocol.org/definitions/token-types/pic"
  ],

  "issued_token_types_supported": [
    "https://pic-protocol.org/definitions/token-types/pic"
  ],

  "artifact_hash_alg_values_supported": [
    "sha-256"
  ],

  "token_endpoint_auth_methods_supported": [
    "none"
  ],

  "token_exchange_parameters_supported": [
    "continuity_proposal"
  ],

  "pic_context_of_authority": {
    "formats_supported": [
      "pic-pca+cose"
    ],
    "signing_alg_values_supported": [
      "ES256"
    ]
  },

  "pic_continuity_proposals": {
    "parameter": "continuity_proposal",
    "types_supported": [
      "https://pic-protocol.org/definitions/proposal-types/continuity-initial"
    ]
  },

  "pic_continuity_transition": {
    "formats_supported": [
      "pic-continuity-transition+cose"
    ],
    "signing_alg_values_supported": [
      "ES256"
    ]
  },

  "pic_continuity": {
    "formats_supported": [
      "pic-continuity+cose"
    ],
    "signing_alg_values_supported": [
      "ES256"
    ],
    "continuity_modes_supported": [
      "centralized-continuity"
    ]
  },

  "pic_token": {
    "token_type": "https://pic-protocol.org/definitions/token-types/pic",
    "formats_supported": [
      "pic+jwt"
    ],
    "signing_alg_values_supported": [
      "ES256"
    ]
  }
}

The pic_context_of_authority, pic_continuity_proposals, pic_continuity_transition, pic_continuity, and pic_token names are intentionally explicit. They identify top-level PIC-X profile capabilities rather than generic OAuth server capabilities.

Capability Summary

The formats_supported values are PIC format identifiers. For COSE artifacts, they are not automatically RFC 9596 COSE typ values. Artifact hash algorithms describe PIC signed-artifact references, not JOSE/COSE signing algorithms or SD-JWT internal hashing.

continuity_modes_supported = ["centralized-continuity"] describes the supported continuity advancement model. It is not a generic feature or policy bag.

The Initial Continuity Proposal has:

type = https://pic-protocol.org/definitions/proposal-types/continuity-initial

It is carried by the continuity_proposal parameter as compact UTF-8 JSON encoded with unpadded Base64url. It is not itself a JWT, COSE artifact, or signed PIC artifact.

In Profile 0.2, a settled Continuity has transitions = null. A candidate Continuity has transitions containing exactly one PIC Continuity Transition COSE.

Execution contract material is represented consistently across layers:

initial proposal input -> executionContract
logical PCA -> execution.contract
canonical PIC PCA COSE Indexed Authority Map -> execution_contract
continuity attenuation -> attenuations.execution_contract.additions

The execution contract constrains execution. It does not grant authority. Accepted continuity additions may only add restrictions and are combined with existing constraints using logical AND.

Token Exchange Summary

PIC-X uses OAuth Token Exchange as the exchange interface for this profile:

urn:ietf:params:oauth:grant-type:token-exchange

OAuth is one entry and integration mechanism for PIC. It is not a universal dependency of the PIC model.

subject_token_types_supported advertises both accepted subject token categories:

urn:ietf:params:oauth:token-type:access_token
-> supported for OAuth-to-PIC initialization

https://pic-protocol.org/definitions/token-types/pic
-> supported for PIC-to-PIC continuity advancement

The returned artifact is a PIC Token JWT:

{
  "access_token": "<signed-pic-token-jwt>",
  "issued_token_type": "https://pic-protocol.org/definitions/token-types/pic",
  "token_type": "N_A"
}

access_token is the OAuth Token Exchange response field. The returned value is a PIC Token JWT, not an OAuth Bearer access token.

For initialization, PIC-X validates the OAuth access token and Initial Continuity Proposal, derives PCA 0, signs the initial PIC PCA COSE and settled PIC Continuity COSE, and returns PIC Token JWT 0.

For advancement, PIC-X parses the candidate PIC Token JWT, candidate PIC Continuity COSE, and embedded Transition as untrusted input. It then validates the current checkpoint, predecessor, position, challenge, Proof of Relationship, workload signatures, attenuation, non-expansion, revocation, local policy, and evidence or conformance checks required by the selected profile.

The detailed PCA derivation and centralized advancement walkthroughs are covered by the later PIC-X articles.

Trust Boundary

issuer identifies the realm that issues settled PIC artifacts. The server control plane has no corresponding token issuer identity.

Profile 0.2 uses proof_of_relationship.type = "sd-jwt" and issuer-signed SD-JWT presentation bytes in proof_of_relationship.evidence for PIC Continuity Transition COSE. SD-JWT support does not make every issuer automatically trusted for PoR; trust depends on selected realm configuration, issuer validation, key validation, and profile rules.

No separate SD-JWT KB-JWT is required for continuity advancement in this profile. Generic attestation proof-of-possession capabilities do not imply a mandatory PIC continuity mechanism.

Discovery advertises how the realm exchanges, issues, and validates artifacts. It does not change the non-expansion invariant: accepted PIC authority cannot expand beyond its established origins and valid restrictions.

Transport / Security Notes

PIC-Token is the HTTP binding for a PIC Token JWT:

PIC-Token: <signed-pic-token-jwt>

The underlying PIC Token JWT and embedded COSE artifacts are transport-independent. They may be carried over HTTP, RPC systems, event streams, queues, workflow engines, or storage-backed execution systems.

PIC artifacts are signed, not encrypted. Signatures protect integrity and identify a signer only after key identity and trust binding have been validated. They do not provide confidentiality and do not prevent copying by themselves.

Possession of a PIC Token JWT alone is not sufficient to advance continuity: advancement additionally requires an accepted Proof of Relationship, workload signatures verified against the PoR-bound key, predecessor, challenge, and position validation, non-expansive attenuation, execution-contract conformance where required, revocation, and policy validation. Within the set of workloads that can pass those checks, however, the settled PIC Token JWT exposes a continuation opportunity: an eligible workload that receives it may propose its own sibling continuation. Confidentiality of token delivery is therefore an important deployment security control, because disclosure can expose an eligible continuation opportunity to unintended workloads; it is not a substitute for, or a source of, PIC continuity validation.

Deployments still need transport security: TLS for HTTP, mTLS or equivalent peer authentication when required, broker authentication and authorization for messaging systems, and revocation validation for relevant PIC artifacts or continuity state.

A PCA has no mandatory independent expiration. Any expiration policy is profile-defined. A PIC PCA COSE is usable only as part of a valid PIC Continuity COSE carried by a PIC Token JWT and remains subject to revocation, continuity rules, execution-contract constraints, local policy, and any declared token or profile expiration.

References

External References

• RFC 8414 — OAuth 2.0 Authorization Server Metadata
• RFC 8693 — OAuth 2.0 Token Exchange
• RFC 7517 — JSON Web Key (JWK)
• RFC 7519 — JSON Web Token (JWT)
• PIC Protocol
• PIC Prover and Verifier Specification
• PIC Revocation Specification
• PIC Sandboxed Execution
• PIC Architecture and Deployment Specification

PIC-X Series

• Designing PIC-X: From Specification to Architecture to Code
• Designing PIC-X: Deriving an Initial PIC Context of Authority
• Designing PIC-X: PIC Token JWT and COSE Artifacts