Documentation
¶
Overview ¶
admin_audit.go — a generic, unopinionated admin-mutation audit seam (companion to the extension.go org/auth seams).
State-changing admin routes (e.g. the agent patterns/services clears, shadow/detect clears, and the manual service / attribution-override mutations) call RecordAdminAudit after they succeed OR when they reject a request. OSS ships NO hook, so every call is a community-mode no-op and an untouched OSS binary behaves exactly as before — there is no audit backend in the open-core tree. An external wrapper (the enterprise build) registers a hook that writes the event into its append-only, per-org audit trail.
The hook is handed the request ctx (not a pre-extracted actor/org) so the implementation can derive the operator identity and tenant the way it authenticates requests — OSS has no concept of an SSO principal or a tenant, so resolving those belongs entirely to the wrapper.
Registration is process-wide and expected to happen once at boot, before the server starts accepting connections.
extension.go — generic, unopinionated extension seams.
These are registration hooks the OSS server exposes so an external module (the enterprise build, or any third-party wrapper) can attach behaviour WITHOUT the OSS tree depending on it. Nothing here is enterprise-specific: the defaults are community-mode no-ops, so an untouched OSS binary behaves exactly as before.
Two seams:
- Org injection — a request-context org id, resolved per request and defaulting to storage.DefaultOrgID ("default"). Single-tenant OSS never sees it; a multi-tenant wrapper registers a resolver that reads the org from a header/token.
- Auth slot — a settable middleware that runs on the API surface ahead of the OSS gateway-secret checks. OSS registers none (the slot is a pass-through); a wrapper registers SSO/JWT enforcement. A registered handler may call MarkAuthorized to tell the OSS gateway-secret guards the request is already authenticated by an alternative credential (e.g. an SSO session), so one enterprise credential can unlock both the data plane and the admin surfaces.
Registration is process-wide and expected to happen once at boot, before the server starts accepting connections.
Index ¶
- Constants
- func AuthMiddleware() fiber.Handler
- func Logger() fiber.Handler
- func MarkAuthorized(c *fiber.Ctx)
- func OrgFromContext(c *fiber.Ctx) string
- func OrgInjector() fiber.Handler
- func RecordAdminAudit(c *fiber.Ctx, action, target, result string)
- func RequestAuthorized(c *fiber.Ctx) bool
- func SetAdminAuditHook(h AdminAuditHook)
- func SetAuthMiddleware(h fiber.Handler)
- func SetOrgResolver(r OrgResolver)
- type AdminAuditEvent
- type AdminAuditHook
- type OrgResolver
Constants ¶
const ( // AdminAuditSuccess — the mutation completed. AdminAuditSuccess = "success" // AdminAuditDenied — the mutation was rejected (validation, precondition, // conflict, or a gate). AdminAuditDenied = "denied" )
Admin-audit outcome strings. A destructive admin action records exactly one of these; they mirror the wrapper's audit-result vocabulary without the OSS tree depending on it.
const AuthorizedContextKey = "versus.authorized"
AuthorizedContextKey is the fiber Locals key a registered auth handler (see SetAuthMiddleware) sets to mark a request as already authenticated by an alternative credential — e.g. an enterprise SSO session. The OSS gateway-secret guards honour this flag and skip the X-Gateway-Secret check when it is set, so a single enterprise credential can unlock both the data plane and the admin surfaces.
const OrgContextKey = "versus.org_id"
OrgContextKey is the fiber Locals key under which the resolved org id is stored for the lifetime of a request.
Variables ¶
This section is empty.
Functions ¶
func AuthMiddleware ¶ added in v1.4.4
AuthMiddleware returns the registered auth handler, or a no-op pass-through when none is registered (community mode).
func MarkAuthorized ¶ added in v1.4.4
MarkAuthorized records that the current request was authenticated upstream by a registered auth handler. Community OSS never calls this, so the gateway-secret guards behave exactly as before.
func OrgFromContext ¶ added in v1.4.4
OrgFromContext returns the org id stamped on the request by OrgInjector, or storage.DefaultOrgID when none was set.
func OrgInjector ¶ added in v1.4.4
OrgInjector returns middleware that stamps the resolved org id onto the request context. With no resolver registered (or a resolver that returns ""), every request is scoped to storage.DefaultOrgID, which is invisible to single-tenant OSS users.
func RecordAdminAudit ¶ added in v1.4.7
RecordAdminAudit emits one admin-mutation audit event to the registered hook. With no hook registered (community mode) it is a no-op, so an OSS binary is byte-inert. Callers pass a freshly built, non-secret target string.
func RequestAuthorized ¶ added in v1.4.4
RequestAuthorized reports whether a prior auth handler marked this request authorized. It defaults to false (community mode), leaving the OSS gateway-secret checks unchanged.
func SetAdminAuditHook ¶ added in v1.4.7
func SetAdminAuditHook(h AdminAuditHook)
SetAdminAuditHook registers the hook invoked for every state-changing admin action. OSS ships none (the slot is a no-op). Passing nil clears it (back to the community no-op). Call at boot.
func SetAuthMiddleware ¶ added in v1.4.4
SetAuthMiddleware registers an extra auth handler that runs on the API surface ahead of the OSS gateway-secret checks. OSS ships none. Passing nil clears the slot (back to the community pass-through). Call at boot.
func SetOrgResolver ¶ added in v1.4.4
func SetOrgResolver(r OrgResolver)
SetOrgResolver registers the function used to resolve an org id from a request. OSS ships none, so every request resolves to the default org. Passing nil clears it. Call at boot.
Types ¶
type AdminAuditEvent ¶ added in v1.4.7
AdminAuditEvent describes one state-changing admin action for the audit seam. Action is a stable, namespaced verb (e.g. "agent.patterns.cleared"); Target is the non-secret object acted upon (a service name, override id, or a reset summary); Result is one of the AdminAudit* outcome strings.
type AdminAuditHook ¶ added in v1.4.7
type AdminAuditHook func(c *fiber.Ctx, ev AdminAuditEvent)
AdminAuditHook records one admin mutation. It receives the request ctx so an implementation can derive the actor, org and request provenance. OSS ships none (community no-op).
type OrgResolver ¶ added in v1.4.4
OrgResolver extracts the org id for a request. Returning "" means "no explicit org" and falls back to storage.DefaultOrgID.
Source Files