Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication and Authorization Model

​
Audience

This page is for platform security designers, backend implementers, CLI/Agent integrators, and operators who need to understand production guardrails.

​
Goal and Scope

This page defines the roles of AuthN, AuthZ, and Approval, the shared execution chain, and why production mutations require step-up and approval.

​
Core Concepts

​
AuthN

AuthN handles identity validation, session/token management, and principal derivation.

​
AuthZ

AuthZ evaluates action/resource/environment context and returns allow / deny / require_approval.

​
Approval

Approval records, validates, and audits high-risk production authorizations.

​
Task

Task records execution state, progress, and result. It is not another name for Approval, and it does not replace Approval’s decision semantics. Approval records whether a high-risk action may enter the execution chain; Task records what happens after execution begins.

​
Standard Workflow

AuthN -> AuthZ -> Approval(if required) -> Execute -> Audit

​
Current Control-Plane Status And Approval Surfaces

Before formal OpenAPI publishing, the currently frozen minimal control-plane surfaces are:
  • GET /api/v1/system/info
  • GET /api/v1/authn/status
  • GET /api/v1/authz/status
  • POST /api/v1/approvals
Boundary rules:
  • /api/v1/system/info is the platform-level aggregated status entry and does not replace /healthz or /readyz.
  • authn/authz status are visibility-only surfaces; they must not expose tokens, session inventories, raw policy tables, or live per-subject authorization results.
  • POST /api/v1/approvals is now a shipped approval-ticket creation surface; it returns 201 Created with the full binding context when the approval repository is configured, and a structured 503 Service Unavailable when it is not.
  • The intended behavior for the status surfaces is 200 OK with a JSON status object that clearly distinguishes placeholder / ready / degraded, instead of continuing to return 501 Not Implemented.
Approval ticket creation must preserve at least these binding semantics:
  • required binding: subject_id, env, resource_hash, action
  • recommended binding: command_hash
  • a nonce must always exist, and the ticket must become invalid after successful consumption

​
Planned CLI Example (Not Yet Implemented)

The repository does not currently ship this approval request subcommand. The HTTP approval write surface is also still reserved rather than a shipped executable entrypoint. 
aios approval request \
  --action deploy.app.update \
  --resource app:project/prod/my-api

​
Web UI Path

  • login and identity context
  • production approval flow
  • authorization failure and approval-required prompts

​
Pitfalls / Risk Notes

  • Better Auth does not replace business authorization.
  • long-lived JWTs must not carry mutable authorization state.
  • any prod write path that bypasses approval is an architectural violation.
  • AI and automation access at the platform boundary must remain constrained by AuthZ, Approval, and audit instead of becoming a privileged escape hatch.
  • AiOS owns platform-level boundaries; it does not provide fine-grained approval for every coding-tool command inside a DevBox.