Identity and access

Hikyo separates identity from authorization. Authentication proves a principal; a scoped capability decides what that principal may do.

Principal typesCopy Anchor Link

An instance capability is an instance-scoped grant held by a principal, not a third principal type. A machine identity does not get a separate, broader policy model.

Capabilities and scopeCopy Anchor Link

A grant combines one principal, one capability atom, and one scope. Scopes may be instance, organisation, project, or environment level.

Prefer the narrowest scope that permits the task. A deployment reader usually needs one project and environment, not the full organisation.

hikyo access grant add \
  --principal <principal-id> \
  --capability <capability>

Use access grant list before and after a change. Use a named grant template when the built-in role exactly matches the job.

Access rulesCopy Anchor Link

An access rule gives one person one capability on a narrower where than a grant can: a list of projects, then every environment except some (or only some), then every key except some folders or keys (or only those). An exception narrows only its own rule; access is the union of everything a person’s grants and rules reach, and there are no deny rules. Rules are for people; machines keep their grants.

hikyo access rule add --project <project-id> \
  --principal <principal-id> --capability reveal \
  --except-env <prod-env-id> --only-folder db
hikyo access rule list --project <project-id>
hikyo access rule remove <rule-id>

read and pin cannot be narrowed by keys. edit, publish, reveal, reveal-history, definitions-edit and manage-members may be narrowed by keys; publishing still checks group closure and the resulting environment state. Machine, deploy and settings administration need a whole project. An except of a folder also covers its subfolders; an only-pick of a folder is exact. The browser’s Edit rule replaces the selected rule atomically. The CLI’s current rule commands add, list and remove rules; removing and then adding is two operations.

Moving a key to another folder can give people access through their rules. Such a move is refused until it is confirmed with --confirm-widening naming exactly those people; only a member manager of the project is told who they are.

Human onboardingCopy Anchor Link

Registration is closed by default. An administrator can create an organisation or instance registration policy that admits selected identity providers, verified local email sign-up, or both, and defines the landing authority. An instance policy that creates fresh organisations also requires an admission cap. Local email sign-up requires configured mail delivery and a stable public origin; federated sign-up requires an enabled OIDC or supported OAuth2 provider. SAML provisioning uses its separate identity and SCIM path.

The browser exposes registration policy in instance or organisation administration. A permitted registration method appears on the sign-up page; without a policy the door stays closed. Email verification establishes a local sign-in address, never an account-linking or password-recovery key. An existing account links a provider through its authenticated account-security ceremony.

Use the social sign-in runbook for Google, tenant-specific Microsoft Entra and GitHub app setup, policy admission and CLI sign-in. The signup mail runbook covers transport inputs, explicit test delivery and verification failures.

Human sessionsCopy Anchor Link

The local CLI login prompts on the controlling terminal. Passwords never cross argv. Sessions are stored in the local Hikyo state directory with mode 0600.

hikyo login https://hikyo.example.com --tls-mode system-ca --local --as alice
hikyo whoami --instance https://hikyo.example.com
hikyo logout --instance https://hikyo.example.com

Account recoveryCopy Anchor Link

Credential-establishment and recovery authorities are single-use, expiring, and do not create sessions. Deliver them out of band.

The local hikyo admin path exists for bootstrap and break-glass recovery. Host authority is separate from network authorization and may perform named recovery operations that the network path refuses. Those actions remain distinct in the audit trail.

Indistinguishable refusalCopy Anchor Link

An unauthorized resource returns the same external result as a missing one. This prevents resource discovery through permission errors.

Next: configure a human target or create a machine identity.