Files
zeekay 0d308c0fa4 An org's roles are owner, admin and member, and its owner role is moved only by an owner
Only an owner, or a SuperAdmin, deletes an org (the op seam asks
authz OwnerOf) or gives, takes or hands over the owner role; an admin
runs members and admins, and an application that administers orgs owns
nothing. PUT /v1/iam/memberships sets the org-wide role one holds.
The last owner stays: the store refuses, in the same transaction, the
delete, demotion or account removal that would leave an org with none.
No other person writes an owner's account: an admin who could reset it
could sign in as the owner.

A workspace or project row admits its org as a member and administers
nothing there, in the orgs claim and in the Guard alike, so a space's
owner no longer reads as its org's admin. A home account's role is the
higher of its isAdmin bit and its home row.

Only the admin org's own accounts are its members: EnsureMembershipIn
refuses any other, whoever asks. An org created with a founder is born
owned; at boot every ownerless org gets the founder it recorded, and
the orgs with none and the admin-org memberships of other orgs'
accounts are each filed once on the audit trail. Every role change and
org delete is recorded under the org.
2026-09-29 10:36:55 -07:00

138 lines
6.7 KiB
Go

// Copyright 2026 Hanzo AI, Inc.
// SPDX-License-Identifier: MIT OR Apache-2.0
package schema
import "github.com/hanzoai/orm"
// AuditLog is an append-only action record (v1 the legacy surface `record`, v2 kind
// "audit_logs"). One row captures a single request against the IAM surface:
// who acted (Organization, User, ClientIp), what they invoked (Method,
// RequestUri, Action), the request payload and the server's answer (Object,
// Response, StatusCode), and whether the row fired its registered webhooks
// (IsTriggered). It is written once at request time and is not mutated in
// normal operation; the CRUD update path exists only for administrative
// correction.
//
// Identity is the (Owner, Name) pair — Name is a generated unique id and Owner
// is the acting organization — so the orm string key is "owner/name". v1's
// integer autoincrement primary key (`id`) is a per-store surrogate with no
// cross-store meaning; it is superseded by the orm string key rather than
// carried as a colliding `id` field, since orm.Model already persists its own
// `id`. Every semantically meaningful v1 column is carried so no actor,
// endpoint, payload, or status is lost on migration.
//
// Object and Response are unbounded text in v1 (mediumtext): Object holds the
// password-masked request body and Response a compact status/message envelope.
// Both carry no orm index. The audit query dimensions — Organization, User, and
// Action — are indexed alongside the (Owner, Name) key and the CreatedTime sort
// column.
// The actions the PLATFORM writes about itself. A row carrying one of these is
// not a customer's own telemetry: it is the evidence that the platform did
// something accountable — recorded a consent answer, issued or revoked a
// credential. The generic audit-log CRUD refuses to create, alter or delete one,
// so the trail cannot be forged with an invented grant or quietly trimmed of a
// real one by the same org admin whose actions it records.
//
// They live here, beside the entity, because the WRITERS (internal/oidc) and the
// GATE (internal/auditlogs) are different packages and must name the same set. A
// writer that invents its own string writes a row anybody can then rewrite.
const (
ActionConsentTraining = "consent-training"
ActionIssueUserToken = "issue-user-token"
ActionMintUserKeys = "mint-user-keys"
ActionRevokeUserKeys = "revoke-user-keys"
ActionTokenExchange = "token-exchange"
// A server key acting FOR a user in its own org — the credential behind as().
// It is a privileged mint (one principal obtains a token bound to another), so
// every one is recorded: who acted (the org key), for whom (the target
// subject), in which org, and when.
ActionAs = "as"
// A platform operator stepping into an organization and back out, and reaching
// past their own memberships to enumerate the registry. All three are
// privileged cross-tenant acts, so all three are recorded — and so is a
// refusal, which is the row an auditor most wants to find.
ActionAssumeOrg = "assume-organization"
ActionReleaseOrg = "release-organization"
ActionListOrgs = "list-organizations"
// A request a SuperAdmin made with platform authority — every one the Guard
// admits for them, read or write, whatever its route and answer — and the
// platform acts IAM performs for one outside the Guard: unlinking another
// person's sign-in method. Filed under the actor's own org, the admin org,
// so the whole trail of platform authority is one query; Organization names
// the org acted on when there is one.
ActionSuperAdmin = "superadmin"
// A token minted with SuperAdmin authority, recorded before it is released.
ActionSuperAdminToken = "superadmin-token"
// A workload in a Kubernetes namespace obtaining its application's token by
// presenting the ServiceAccount token its cluster minted for it (RFC 7523).
// The row names the service account that asked, so the trail reads the same
// whether a credential came from a stored secret or from the cluster.
ActionWorkloadToken = "workload-token"
// Invitations: an email sent about one, an account joining an org through one,
// and the refused attempts to use one — by a signed-in account, and at signup.
// They are the ledger the send quotas and the attempt limits count, which is
// why no request may create, alter or remove them.
ActionInviteSend = "invitation-send"
ActionInviteAccept = "invitation-accept"
ActionInviteRefused = "invitation-refused"
ActionInviteSignupRefused = "invitation-signup-refused"
// A code IAM sent a signed-in account to prove its address for joining.
ActionInviteCodeSent = "invitation-code-sent"
// An org's roles: a person given, moved between or relieved of owner, admin
// or member (Object: user, from, to), and the org itself deleted. Filed
// under the org; User is who acted, empty when IAM did.
ActionOrgRole = "organization-role"
ActionOrgDelete = "organization-delete"
// Findings IAM files once at boot: an org with no owner and no founder to
// make one (Object: the founder recorded, if any), and an admin-org
// membership held by an account of another org (Object: the account).
ActionOrgOwnerless = "organization-ownerless"
ActionAdminOrgStranger = "admin-organization-stranger"
)
// PlatformWritten reports whether action names a record the platform writes
// about itself, and which therefore no request may create, alter, or remove.
//
// Read this; never compare the strings. A caller with its own comparison is a
// second copy of the reserved set, and the two will drift the moment one grows.
func PlatformWritten(action string) bool {
switch action {
case ActionConsentTraining, ActionIssueUserToken, ActionMintUserKeys,
ActionRevokeUserKeys, ActionTokenExchange, ActionAs,
ActionAssumeOrg, ActionReleaseOrg, ActionListOrgs, ActionSuperAdmin, ActionSuperAdminToken, ActionWorkloadToken,
ActionInviteSend, ActionInviteAccept, ActionInviteRefused, ActionInviteSignupRefused,
ActionInviteCodeSent, ActionOrgRole, ActionOrgDelete, ActionOrgOwnerless, ActionAdminOrgStranger:
return true
}
return false
}
type AuditLog struct {
orm.Model[AuditLog]
Owner string `json:"owner" orm:"index"`
Name string `json:"name" orm:"index"`
CreatedTime string `json:"createdTime" orm:"index"`
Organization string `json:"organization" orm:"index"`
ClientIp string `json:"clientIp"`
User string `json:"user" orm:"index"`
Method string `json:"method"`
RequestUri string `json:"requestUri"`
Action string `json:"action" orm:"index"`
Language string `json:"language"`
Object string `json:"object"`
Response string `json:"response"`
StatusCode int `json:"statusCode"`
IsTriggered bool `json:"isTriggered"`
}