`@prox-os/security-ui`

What is @prox-os/security-ui?

@prox-os/security-ui is the OS-native security presentation package for Prox OS. It defines frontend contracts and React primitives for principals, security resources, access levels, permission grants, risks, policy notices, security events, audit events, sessions, devices, integration tokens, and access reviews.

It is a UI and contract package. It does not authenticate users, enforce access control, evaluate policy, store audit logs, manage secrets, or scan systems.

Why Prox OS Needs Security UI Primitives

Prox OS is a browser-based OS shell where apps, files, AI tools, notifications, collaboration threads, search results, workspace resources, and future activity events all need to explain safety state in one vocabulary. Apps should be able to show "this file is public", "this AI tool call is high risk", "this session is new", or "this token has dangerous scopes" without each app inventing its own security model.

Package Scope

• Serializable TypeScript contracts for security view models.
• React primitives for badges, alerts, permission panels, audit lists, sessions, token scopes, access reviews, policy notices, and security summaries.
• Mock security data for Storybook and documentation examples.
• Adapter examples from actions, AI UI, files, notifications, search, collaboration, workspace, command, activity, and generic resources.

Non-Goals

• No auth provider integration.
• No RBAC/ABAC or policy engine.
• No permission enforcement or route interception.
• No cryptography, KMS, scanner, DLP, SIEM, or compliance automation.
• No secret creation, storage, display, or revocation backend.
• No shell-private imports.

Core Concepts

• Principal: user, guest, team, workspace, app, agent, integration, or system actor.
• Security resource: app, route, workspace, file, AI session, tool call, notification, review, integration, external URL, or system object.
• Access and visibility: display-level metadata such as private, restricted, public link, or public indexed.
• Permission grant: one principal's permission on a resource, including inherited/source metadata.
• Risk, trust, sensitivity: presentation model for warnings and review flows, not an enforcement result.
• Policy notice: human-readable notice explaining a sharing, AI, file, workspace, integration, session, or developer policy state.
• Security and audit event: focused lists for security-centered events. Activity timeline remains a future package concern.
• Session and device: UI metadata for active, current, expired, or revoked sessions and device trust.
• Integration token: masked metadata and scopes only. Real secrets are never generated or displayed.
• Access review: human-in-the-loop review object for public sharing, sensitive context, workspace role changes, and high-risk AI actions.

Core API

• Types: OsSecurityPrincipal, OsSecurityResourceRef, OsPermissionGrant, OsPermissionSet, OsSecurityRisk, OsSecurityPolicyNotice, OsSecurityEvent, OsAuditEvent, OsSecuritySession, OsSecurityDevice, OsTokenScope, OsIntegrationToken, OsAccessReviewRequest, OsSecurityUiEvent.
• Helpers: labels, permission checks, risk checks, sensitivity/public visibility checks, grouping, summaries, policy notice factories, and access review factories.
• Adapters: action intents, AI risk/context, file public-link/sensitivity, security notifications, search documents, collaboration sharing/review, workspace roles, activity drafts, command metadata, and generic resources.

React Primitives

• Badges: OsSecurityBadge, OsRiskBadge, OsTrustBadge, OsAccessLevelBadge, OsSensitivityBadge, OsPermissionBadge.
• Alerts: OsSecurityAlert, OsRiskBanner, OsPublicLinkWarning, OsSensitiveContextNotice, OsPolicyNotice.
• Permissions: OsPermissionMatrix, OsPermissionList, OsAccessPanel.
• Events: OsSecurityEventItem, OsSecurityEventList, OsAuditEventItem, OsAuditLogList.
• Sessions and tokens: OsSessionCard, OsSessionList, OsDeviceCard, OsTokenScopeList, OsIntegrationPermissionCard.
• Reviews and states: OsAccessReviewCard, OsSecuritySummaryPanel, OsSecurityEmptyState, OsSecurityLoadingState, OsSecurityErrorState.

Mock Data

The package exports mock principals, resources, permission sets, security events, audit events, sessions, devices, policy notices, access reviews, integration tokens, and a summary snapshot. The mock set covers app permissions, workspace roles, file public links, sensitive AI context, risky AI tool calls, security notifications, audit events, sessions/devices, token scopes, access reviews, collaboration security, and developer warnings.

Storybook Examples

The UI Workshop includes:

• Security UI / Overview
• Security UI / Badges
• Security UI / Risk Alerts
• Security UI / Permissions & Access Panel
• Security UI / Public Link & Sensitive Context
• Security UI / Security Events & Audit Log
• Security UI / Sessions & Devices
• Security UI / Token Scopes & Integrations
• Security UI / Access Reviews & Policies
• Security UI / AI Files Notification Security
• Security UI / Workspace Collaboration Security
• Security UI / Developer Security Warnings

Integration Boundaries

• @prox-os/actions: security UI produces action intents such as revoke session, disable public link, request review, approve/reject access review, revoke token, or open a security target. It does not execute them.
• @prox-os/ai-ui: AI risk, tool call approvals, and sensitive context can map to security notices and reviews. Security UI does not run AI.
• @prox-os/files: file public links, sensitivity, and access metadata can map to security resources. Security UI does not manage files.
• @prox-os/notifications: security events can map to notification drafts. Security UI does not own the notification center.
• @prox-os/search: security events, audit events, and access reviews can map to searchable documents. Security UI does not search.
• @prox-os/collaboration: external collaborators, public review links, and sharing reviews can map to security warnings. Security UI does not own threads or reviews.
• Future @prox-os/workspace-ui and @prox-os/activity can consume these view models without moving their runtime responsibilities into this package.

Roadmap

Phase 1

• TypeScript contracts.
• Mock principals, resources, permissions, events, audit entries, sessions, tokens, and access reviews.
• Security badges, alerts, permission/access panel, audit/session/token/access review UI primitives.
• Helpers and adapters.
• Storybook examples and docs.
• No real auth provider, enforcement, or audit persistence.

Phase 2

• Define OsSecurityProvider and OsPermissionProvider interfaces.
• Mock and local state providers.
• Permission request flow adapter.
• Security event subscription shape.
• Access review state adapter.
• Policy notice registry.

Phase 3

• OS security center panel.
• App, window, and resource-level security summaries.
• File public-link and workspace sharing warnings.
• AI tool-call approval handoff.
• Notification, search, activity, and command palette integration.

Phase 4

• Backend auth/session provider.
• RBAC/ABAC policy provider.
• Audit log API.
• Token/integration management API.
• Cloudflare Access / Zero Trust integration.
• Per-workspace security policy routing.

Phase 5

• AI safety policy router.
• Prompt-injection and sensitive-context UI flows.
• Agent permission sandbox UI.
• Community app trust score.
• /@creator/apps/... trust and moderation surfaces.

Acceptance Checklist

• The package is recognized by the pnpm workspace.
• src/index.ts exports types, helpers, adapters, mock data, and components.
• Storybook renders core states without a real auth/security backend.
• No deep import from apps/os-shell.
• No auth SDK, policy engine, KMS, scanner, SIEM, or audit backend dependency.