mix attesto_phoenix.install (AttestoPhoenix v3.2.1)

Copy Markdown View Source

Installs the attesto_phoenix authorization-server layer into a Phoenix app

Wires the OAuth 2.0 / OpenID Connect authorization-server layer this library provides into the host Phoenix application:

  • adds an AttestoPhoenix.Config config skeleton (issuer, audience, keystore, repo, principal kinds, the Ecto-backed token stores, a chosen :oauth_path_prefix, optional :schema_prefix, and neutral defaults) to the host config, and points the library's global resolver and stores at that OTP app/repo,
  • adds runtime refresh-successor encryption configuration: production reads ATTESTO_REFRESH_SUCCESSOR_SECRET; the bundled Ecto store fails config validation when positive retry grace needs it but custom stores and strict zero-grace deployments do not; development and test use a per-project fallback generated when this task runs,
  • supervises AttestoPhoenix.Store.Sweeper after the host repo so expired Ecto rows are reclaimed and refresh-successor ciphertext is redacted promptly after its short retry window,
  • mounts the server routes (attesto_routes/1) at the chosen prefix into the host router behind a generated config-loading pipeline,
  • scaffolds host callback modules implementing the recommended production behaviours (AttestoPhoenix.ClientStore, PrincipalStore, ScopePolicy, ConsentPolicy, RegistrationStore, EventSink) with documented stub callbacks the host fills in,
  • points the host at mix attesto_phoenix.gen.migration for the Ecto tables the bundled stores read, including the durable refresh-family revocation tombstones. Existing 2.x installations use the generated --upgrade 3.0 and --upgrade 3.1 migrations, in that order, while writers remain stopped. Each validates canonical pre-existing objects before adoption; custom layouts need a reviewed migration.

Every step is idempotent: re-running the task does not duplicate the config, the route, or the scaffolded modules. The task never decides authorization policy; it scaffolds the contract the host owns (RFC 6749 §2/§3.3/§4.1.1, RFC 7591 §3, OpenID Connect Core §3.1.2/§5.3) and emits notices telling the host exactly what to fill in.

Example

mix attesto_phoenix.install

Options

  • --oauth-path-prefix - the full client-visible mount prefix for the bundled OAuth endpoints (RFC 8414 §3 advertises the absolute URLs). It must be /oauth or end in /oauth, because the bundled router has fixed /oauth/* endpoint tails; for example, --oauth-path-prefix /mcp/oauth generates attesto_routes(prefix: "/mcp") and advertises /mcp/oauth/*. Unsupported values such as /auth are rejected before any files are changed. If a host needs a different endpoint suffix or an explicit per-endpoint route override, wire the routes manually and set matching advertised paths instead of relying on the generated mount. The well-known documents (RFC 8615) and the JWKS document stay anchored at the host root and are NOT relocated by this prefix.
  • --schema-prefix - the PostgreSQL schema selected by Ecto's prefix: option for every generated table and index. The migration generator uses the same value. On an installer rerun, an explicit value must match the host's existing literal configuration. When different config environments select different concrete schemas, the flag selects the matching non-default branch without rewriting any host config. An omitted/default branch cannot be equated with public, because the connection search path may name another schema. The installer never moves a live database or overwrites an existing selection. The legacy 2.x --table-prefix option and configuration key are rejected because they controlled literal names in generated migrations, not one coherent runtime layout: most stores queried canonical public tables, while only the CIBA store and sweeper treated the value as an Ecto schema prefix.
  • --callbacks-module - the base module the scaffolded callback modules are generated under. Defaults to <App>.AuthZ, yielding <App>.AuthZ.ClientStore and friends.