key-cape/docs/forgejo-oidc-client-request.yaml

# KEY-WP-0038-T01: what Forgejo receives from NetKingdom.
# Proposed, non-secret request packet. This is not executable authorization:
# registration happens in T02 after the founder accepts this packet and
# railiance-apps (RAPPS-WP-0016) agrees the group names.
#
# Context: forgejo.coulomb.social is closing (prj-forgejo-org-refactor
# ORGREF-WP-0002, decisions/forge-visibility-policy.md). Sign-in through
# NetKingdom must exist and be proven before any repository closes.
status: accepted-2026-10-08   # founder, in session; registration is T02
owner: key-cape
consumer: railiance-apps (Forgejo Helm release, namespace forgejo)
issuer: https://kc.coulomb.social

client:
  # Proposed entry for the client registry in T02. Field rules as in
  # spec/canonical-model.yaml Client and KEY-WP-0028 (browser clients carry no
  # serviceSubject or roles).
  clientId: forgejo
  displayName: "Forgejo source forge"
  clientType: confidential          # server-side app; Forgejo holds a secret
  grantTypes: [authorization_code]  # PKCE as well (Forgejo sends S256)
  redirectUris:
    # Exact string. "netkingdom" is Forgejo's authentication-source name and
    # must match RAPPS-WP-0016-T02 character for character.
    - "https://forgejo.coulomb.social/user/oauth2/netkingdom/callback"
  allowedScopes: [openid, profile, email, groups]
  secretRef: env:KEYCAPE_FORGEJO_CLIENT_SECRET
  # The forge holds every repository and its history. Admins and owners must
  # have a fresh second factor, so MFA is pinned on the client rather than
  # left to the deployment default (as noted for openbao-admin on 2026-10-06).
  mfaRequired: true

custody:
  # Minted straight into custody in T02; no value in git, State Hub or chat.
  # Derived by SecurityCaseType oidc-browser-relying-party 1.0 as
  # platform/workloads/keycape/{client_id}; a case may not set it (net-kingdom
  # 074b3a0, after ops-mason MASON-WP-0010-T01). Replaces the earlier proposal
  # platform/workloads/forgejo/netkingdom-oidc-client.
  openbao_path: platform/workloads/keycape/forgejo
  keycape_delivery: ESO Secret sso/keycape-forgejo-client (role external-secrets-keycape-forgejo)
  field: CLIENT_SECRET
  custody_owner: railiance-platform
  keycape_environment: KEYCAPE_FORGEJO_CLIENT_SECRET
  forgejo_side: >-
    railiance-apps delivers the same secret to the forgejo namespace from OpenBao
    for gitea.oauth (RAPPS-WP-0016-T02). key-cape and Forgejo read one custody
    path; neither copies the value.

claims:
  # What the ID token carries for a human signing in to Forgejo, per source at
  # this revision (src/internal/server/oidc/token.go).
  sub: canonical directory subject (stable; Forgejo's link key)
  preferred_username: LLDAP username; emitted with scope profile
  email: LLDAP email; emitted with scope email
  groups: LLDAP group names; always present on human ID tokens
  principal_type: human (browser sign-in is for humans only; see agents_and_services)
  assurance: authentication time and factors; MFA required by the client pin

forgejo_mapping:
  # Proposed. The group names are new LLDAP groups, agreed with railiance-apps
  # before T02. Forgejo reads them with --group-claim-name groups.
  group_claim: groups
  required_claim:
    # Only members of a forge group may sign in at all, so a NetKingdom account
    # alone grants nothing on the forge.
    name: groups
    any_of: [forge-admins, forge-coulomb-owners, forge-coulomb-readers]
  admin_group: forge-admins
  group_team_map:
    forge-coulomb-owners: {coulomb: [Owners]}
    forge-coulomb-readers: {coulomb: [readers]}
  account_creation: >-
    No automatic creation of unknown subjects. Existing local accounts are linked
    by signing in once with the local credential (Forgejo account linking), so
    the founder and agent accounts keep their history, keys and tokens.
  initial_members:
    forge-admins: [the founder]
    forge-coulomb-owners: [the founder]
    forge-coulomb-readers: []        # filled as ORGREF-WP-0002-T06 consumers move

agents_and_services:
  # Decided in T03 with railiance-apps, recorded here when settled.
  proposal: >-
    Agents and services do not use browser sign-in. They read the forge with
    scoped Forgejo tokens (read-only, per consumer, with owner and rotation)
    issued to forge accounts that are bound to a NetKingdom service identity
    (principal_type service). The binding is recorded where the token is
    custodied. Browser OIDC stays human-only, so MFA keeps its meaning.
  open: >-
    Whether Forgejo can accept NetKingdom client_credentials tokens directly (it
    does not today for git or registry access) is not assumed.

acceptance:
  - founder accepts this packet
  - railiance-apps agrees the authentication-source name and the group names
  - LLDAP groups forge-admins, forge-coulomb-owners and forge-coulomb-readers are
    created, with the founder in the first two, before T02