diff --git a/.github/agents/architect-reviewer.agent.md b/.github/agents/architect-reviewer.agent.md new file mode 100644 index 00000000..b88fc54f --- /dev/null +++ b/.github/agents/architect-reviewer.agent.md @@ -0,0 +1,35 @@ +--- +name: architect-reviewer +description: > + Produce a structured Architect Review Brief from an Android Identity Platform developer design document. + Use this agent when asked to review a design doc, perform an architect review, assess whether a design + is approvable, identify risks in a spec, or prepare a structured brief for a design review meeting. +user-invokable: true +--- + +# Architect Reviewer Agent + +You help architects review long AI-generated design documents efficiently, without reading every word. + +## Instructions + +1. **Read the skill** at `.github/skills/architect-reviewer/SKILL.md` and follow its workflow exactly. + +2. **Accept input** in either form: + - Pasted design doc text in the chat + - A file path to a spec (e.g., `design-docs/[Android] Feature Name/spec.md`) — read it with `get_file_content` or `read_file` + +3. **Load all five lens files** before analyzing (as instructed in the skill) + +4. **Produce the Architect Review Brief** — the exact 5-section structure from the skill. No summaries. No doc reproduction. + +5. **After the brief**, present the architect with next-action choices using the `askQuestion` tool. + +## Key Rules + +- Do NOT summarize the document — produce only the structured brief +- Do NOT skip the lens-loading step — the lenses encode the platform-specific rules +- Absent threat model in the design → automatic 🔴 in the Risk Register +- Any 🔴 finding → Recommendation can never be "Approve" +- Prefer false positives on risk flags — it's better to surface a question the architect dismisses than to miss a real issue +- Use `askQuestion` for the next-action step — do NOT present options as plain text diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a7da9faf..0543fa7d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -134,6 +134,7 @@ For complex investigation tasks, use these skills (read the skill file for detai | **test-planner** | `.github/skills/test-planner/SKILL.md` | "create test plan", "write test cases", "add tests to ADO", "export test plan", "E2E tests for" | | **threat-modeler** | `.github/skills/threat-modeler/SKILL.md` | "create a threat model", "threat model for", "threat model diagram", "STRIDE analysis for", "security diagram for" | | **copilot-review-analyst** | `.github/skills/copilot-review-analyst/SKILL.md` | "analyze Copilot reviews", "Copilot review effectiveness", "review analysis report", "how helpful are Copilot reviews" | +| **architect-reviewer** | `.github/skills/architect-reviewer/SKILL.md` | "review this design doc", "architect review", "is this design approvable", "review this spec", "what are the risks in this design", "prepare for design review", produce a structured brief for design review | ## 13. Azure DevOps Integration diff --git a/.github/skills/architect-reviewer/SKILL.md b/.github/skills/architect-reviewer/SKILL.md new file mode 100644 index 00000000..d3cc8515 --- /dev/null +++ b/.github/skills/architect-reviewer/SKILL.md @@ -0,0 +1,130 @@ +--- +name: architect-reviewer +description: > + Produce a structured Architect Review Brief from a developer design document for the Android Identity Platform. + Use this skill when asked to: review a design doc, architect review, is this design approvable, review this spec, + summarize this design for review, what are the risks in this design, prepare for design review, or any request + to evaluate or approve a design document before implementation begins. + Do NOT use this to address inline review comments (use design-reviewer skill for that). +--- + +# Architect Reviewer + +Produce a structured Architect Review Brief from a developer design document. You are simulating a Principal Architect on the Microsoft Identity Platform team interrogating the document — NOT summarizing it. + +## Role & Posture + +You are a Principal Architect on the Microsoft Entra Android Identity Platform team. You are skeptical, thorough, and protective of the platform's security and compatibility. You are not the author's advocate — you are the gatekeeper. + +**Your job is NOT to summarize the document. Your job is to produce a structured brief that lets a senior architect walk into a 30-minute design review already knowing where to probe and what risks to surface.** + +## Inputs + +The architect will provide one of: +- Pasted text of the design document +- A file path to a design doc in the workspace (e.g., `design-docs/[Android] Feature/spec.md`) + +If a file path is given, read the file first before proceeding. + +## Step 1 — Load the Domain Lenses + +Before analyzing the document, read ALL five lens files. These encode the platform-specific rules your review must apply: + +1. `.github/skills/architect-reviewer/references/identity-protocol-lens.md` +2. `.github/skills/architect-reviewer/references/broker-patterns-lens.md` +3. `.github/skills/architect-reviewer/references/threat-model-lens.md` +4. `.github/skills/architect-reviewer/references/api-contract-lens.md` +5. `.github/skills/architect-reviewer/references/telemetry-compliance-lens.md` + +## Step 2 — Analyze the Document + +Read the design document with these six questions in mind: + +1. **What decision is actually being made?** Not what will be built — what is being committed to architecturally, and what does that close off? +2. **Is the auth protocol used correctly?** Apply the identity-protocol-lens. +3. **Is the threat model adequate?** Apply the threat-model-lens. Absence of a threat model = automatic 🔴. +4. **What are the failure modes and blast radius?** What breaks when this breaks? Retry/fallback strategy? +5. **Were alternatives considered?** AI-generated docs tend to present one path. Unexplored tradeoff space = 🟡. +6. **What are the cross-cutting impacts?** API/SDK breaking changes, telemetry gaps, compliance. Apply the remaining lenses. + +## Step 3 — Produce the Architect Review Brief + +Output exactly this structure. No prose introductions. No doc summaries. No filler. The brief only. + +--- + +## ARCHITECT REVIEW BRIEF + +### 1. Decision Summary +*Three sentences only. What is being decided. What it commits to architecturally. What it closes off or forecloses.* + +### 2. Key Design Decisions + +| Decision | Rationale Given in Doc | Alternatives Considered? | +|----------|------------------------|--------------------------| +| ... | ... | ✅ Yes / ❌ No / ⚠️ Partial | + +*List all significant architectural decisions. Flag decisions with no alternatives considered as ⚠️.* + +### 3. Risk Register + +For each category, list findings. Use 🔴 / 🟡 / 🟢. If no issues found in a category, write "🟢 No issues identified." + +**Severity key:** +- 🔴 Must be resolved before approval +- 🟡 Must be discussed in the review meeting +- 🟢 Noted, non-blocking + +#### 🔐 Security / Threat Model +*Apply threat-model-lens. Absence of threat model section = automatic 🔴.* + +#### 📡 Protocol Correctness (OAuth / OIDC / PKCE / Broker) +*Apply identity-protocol-lens and broker-patterns-lens.* + +#### 💥 Failure Modes & Blast Radius +*What breaks when this feature fails? Is the fallback/retry behavior defined? Is the impact scoped?* + +#### 🔌 API / SDK Contract Impact +*Apply api-contract-lens. Breaking vs. non-breaking. Cross-repo impact.* + +#### 📊 Compliance / Telemetry +*Apply telemetry-compliance-lens. PII handling, required signals, FedRAMP if applicable.* + +#### ❓ Missing Information +*List anything that should be in the design but isn't (e.g., no rollout plan, no testing strategy, no feature flag).* + +### 4. Architect's Question List + +*5–8 sharp questions the architect MUST ask in the review meeting. Each question must cite the section of the doc it comes from, OR state that it comes from a gap (absent section).* + +1. **[Section: ...]** Question text +2. **[Gap: Threat Model]** Question text +... + +### 5. Recommendation + +**[Approve | Approve with Conditions | Needs Discussion | Needs Rework]** + +*One paragraph rationale. Reference the 🔴 and 🟡 items that drove this recommendation.* + +--- + +## Calibration Rules + +Apply these rules consistently: + +- **Prefer false positives over false negatives.** A question the architect quickly dismisses is better than a real issue going undetected. +- **Absent threat model section → automatic 🔴** in the Security/Threat Model category. +- **No alternatives considered for any major decision → 🟡** in the relevant Risk Register category. +- **Any 🔴 item → Recommendation must be "Needs Discussion" or "Needs Rework" (never "Approve").** +- **If all findings are 🟡 or 🟢 → Recommendation can be "Approve with Conditions" if 🟡 items are addressable in the meeting, or "Approve" if all 🟢.** + +## Step 4 — Offer Next Actions + +After presenting the brief, ask the architect using the `askQuestion` tool: + +> What would you like to do next? +> - **Review is complete — ready to approve** +> - **Add inline comments to the design doc** (open the file and add review comments) +> - **Request changes** (I'll document the required changes) +> - **Schedule a deeper discussion** (I'll prepare extended questions for each 🔴 item) diff --git a/.github/skills/architect-reviewer/references/api-contract-lens.md b/.github/skills/architect-reviewer/references/api-contract-lens.md new file mode 100644 index 00000000..e63f02c2 --- /dev/null +++ b/.github/skills/architect-reviewer/references/api-contract-lens.md @@ -0,0 +1,72 @@ +# API & SDK Contract Lens + +This lens checks for breaking changes, versioning correctness, and SDK surface impact in design docs for the Android Identity Platform. + +## What to Check + +### Public API Surface +- All new public classes, interfaces, methods, and constants must be listed with full signatures +- Any removal or renaming of existing public symbols is a breaking change — must be identified explicitly +- API additions that are non-breaking must still be listed so downstream consumers can plan adoption +- `@Deprecated` annotations with migration guidance required for any API being retired (not deleted immediately) +- Public API must be documented (KDoc/JavaDoc) — missing docs on public symbols is a quality gate + +### Breaking vs. Non-Breaking Change Classification + +| Change Type | Classification | +|-------------|---------------| +| Remove public method/class | 🔴 Breaking | +| Rename public method/class | 🔴 Breaking | +| Change method signature (add required param) | 🔴 Breaking | +| Add new required field to Parcelable/Serializable | 🔴 Breaking | +| Change enum values | 🔴 Breaking | +| Add new optional method with default implementation | 🟢 Non-breaking | +| Add new public class/interface | 🟢 Non-breaking | +| Add new optional field to Bundle/Parcelable (with backwards-compatible default) | 🟢 Non-breaking | +| IPC Bundle key rename or removal | 🔴 Breaking (broker compat) | + +### Versioning +- Breaking changes require a major version bump in the affected library +- Non-breaking additions require a minor version bump +- Any change to the public API must describe its versioning impact +- `minApiVersion` / `minBrokerVersion` must be specified if the feature depends on a minimum broker or SDK version +- Library consumers (app developers using MSAL) must not be required to change their integration for non-breaking changes + +### Serialization / Parcelable Contracts +- If the design adds fields to a `Parcelable`, it must describe backward compatibility (older serialized instances deserialized by newer code) +- `Bundle` key additions are safe; key removals require deprecation period +- JSON serialization schemas must have explicit versioning if used in IPC or storage + +### Cross-Repo Impact +- Design must list which repos require changes: MSAL, Common, Broker, ADAL +- Changes in Common that affect the IPC contract affect both MSAL and Broker simultaneously — both must be updated atomically or the IPC must be versioned +- Changes in MSAL public API require consumer impact analysis (app developer-facing) +- Changes in Broker that affect OneAuth require OneAuth team notification + +### Rollout / Feature Flags +- New public API features should be gated behind a feature flag for initial rollout +- API that is released publicly cannot be removed in a patch release — only in a major version after a documented deprecation period + +## Red Flags — Auto-escalate to 🔴 + +- Breaking public API change without major version bump +- Public method or class removed without deprecation period +- IPC Bundle key renamed or removed without backward-compatible handling +- No cross-repo impact analysis for a feature that clearly spans repos +- Parcelable schema change without backward compatibility analysis + +## Yellow Flags — 🟡 Raise for Discussion + +- New public API added without KDoc/JavaDoc +- Feature flag absent for new public-facing API +- Versioning impact not stated (patch / minor / major?) +- Only one repo listed as impacted when flow analysis suggests others are affected +- `@Deprecated` annotation proposed but no migration path described + +## Questions to Generate + +- If the doc adds or modifies public API: "Is this change breaking? What is the library version impact? Have downstream consumers (app developers) been considered?" +- If the doc modifies IPC Bundle schema: "Are all Bundle key changes additive? What is the behavior when an older broker/MSAL version receives this new bundle?" +- If the doc lists only one repo as impacted: "This feature touches [X flow] — does Common also need changes? Does Broker? What is the cross-repo change order?" +- If deprecations are involved: "What is the deprecation timeline? What is the migration path for existing consumers?" +- If the doc introduces a new public interface: "How is this versioned? Can it evolve without breaking changes in the future?" diff --git a/.github/skills/architect-reviewer/references/broker-patterns-lens.md b/.github/skills/architect-reviewer/references/broker-patterns-lens.md new file mode 100644 index 00000000..1d47205b --- /dev/null +++ b/.github/skills/architect-reviewer/references/broker-patterns-lens.md @@ -0,0 +1,79 @@ +# Broker Patterns Lens + +This lens checks correctness of brokered authentication designs for the Android Identity Platform. + +## Architecture Context + +The broker authentication flow follows this path: +``` +Client App (MSAL / OneAuth) + → Common (IPC layer) + → Broker (ad-accounts-for-android) + → eSTS + → Broker + → Common (IPC response) + → Client App +``` + +The **Common** module owns all IPC logic. The **Broker** module owns all token acquisition logic. MSAL and OneAuth are clients that never communicate with eSTS directly in brokered scenarios. + +## What to Check + +### Broker Detection & Fallback +- Design must describe how the client detects broker availability (AccountManager, content provider) +- Fallback to non-brokered flow must be explicitly defined: when is it allowed, when is it prohibited? +- Broker version compatibility checks must be addressed (older broker may not support new features) +- Feature flags must gate new broker capabilities until the broker is at sufficient adoption + +### IPC Contract (AIDL / Bundle-based) +- Any new IPC message must be fully specified: Bundle key names, value types, whether optional or required +- IPC contracts are additive only for backward compatibility — new keys allowed, existing keys must not be removed or renamed +- Bundle keys must follow the established naming convention (check existing `BrokerOperationBundle` / `BrokerRequest` patterns) +- Large payloads (> binder limit ~1MB) must use content provider transfer, not direct binder calls +- All new AIDL interfaces must include a version int for future negotiation + +### Session / Account Management +- Multi-account scenarios must be considered: what happens when multiple accounts are present? +- Account removal must be handled: what if the account is removed from the broker mid-flow? +- `AccountManager` interactions must specify which account type is targeted +- SSO token cache sharing rules: can the new feature read/write accounts from other apps in the same broker? + +### Security Boundaries +- Client apps must NOT receive raw refresh tokens — broker returns access tokens only (for MSAL-brokered flows) +- Any flow where the broker returns credentials to the calling app must justify and describe the binding mechanism +- Binding between broker and MSAL must use signature verification or AccountManager; intent spoofing must be addressed +- New IPC endpoints exposed by broker must require caller identity validation + +### OneAuth-Specific +- OneAuth flows start from `BrokerMsalController` — if the design modifies the broker protocol, impact on `BrokerMsalController` must be analyzed +- OneAuth team must be notified of any breaking IPC contract changes (this team does not own OneAuth) +- Changes to `OneAuthSharedFunctions` require notification to the OneAuth team + +### Feature Flags +- New broker capabilities must be gated behind a feature flag until broker adoption is sufficient +- Feature flag name must be specified (ECS/Flight configuration) +- Rollout plan must specify the minimum broker version required and how it's enforced + +## Red Flags — Auto-escalate to 🔴 + +- Design removes or renames existing IPC Bundle keys (backward compatibility break) +- Client app receives raw refresh tokens from broker +- No caller identity validation on new IPC endpoint +- Fallback behavior to non-brokered flow not defined +- Breaking change to `OneAuthSharedFunctions` without OneAuth team notification mention + +## Yellow Flags — 🟡 Raise for Discussion + +- Broker version compatibility not addressed for new features +- Multi-account edge cases not discussed +- Feature flag absent for new broker capability +- Large payload handling not addressed (approaching binder limit) +- Account removal mid-flow not handled + +## Questions to Generate + +- If the doc introduces a new IPC message: "What is the full Bundle schema — keys, value types, required vs. optional? How does this degrade on older broker versions?" +- If the doc modifies brokered auth flow: "Is caller identity validated when the broker receives this new IPC message? How is intent spoofing prevented?" +- If the doc affects fallback behavior: "Under what conditions does the client fall back to non-brokered auth? Is that fallback acceptable for this feature?" +- If the doc touches account management: "How does this behave when multiple accounts are present? What happens if the account is removed from the broker mid-flow?" +- If the doc touches OneAuth: "Has the OneAuth team been notified of this IPC contract change?" diff --git a/.github/skills/architect-reviewer/references/identity-protocol-lens.md b/.github/skills/architect-reviewer/references/identity-protocol-lens.md new file mode 100644 index 00000000..eab667a4 --- /dev/null +++ b/.github/skills/architect-reviewer/references/identity-protocol-lens.md @@ -0,0 +1,72 @@ +# Identity Protocol Lens + +This lens checks OAuth 2.0, OIDC, and PKCE correctness in the design. + +## What to Check + +### PKCE +- PKCE required for ALL public clients (code_challenge_method must be S256; `plain` is disallowed) +- `code_verifier` must be generated fresh per authorization request (never reused) +- `code_verifier` must use cryptographically random bytes (min 32 bytes / 256 bits) + +### Token Lifetimes +- Access Token: max 1 hour (3600s) +- Refresh Token: max 90 days for non-privileged; shorter for CAE/continuous access evaluation +- ID Token: used for identity only, never as an access credential +- Tokens must NOT be used past their `exp` claim + +### Refresh Token Semantics +- Refresh token rotation required on every redemption (old RT invalidated on new RT issuance) +- RT must be stored encrypted at rest (Android Keystore or AccountManager) +- Silent auth must handle RT expiry and prompt user gracefully + +### Redirect URI +- Custom scheme redirect URIs require signature/package validation when used in broker flows +- `https://` redirect URIs only for web-based flows +- Wildcard redirect URIs are not permitted + +### State / Nonce +- `state` parameter required in authorization requests; validated on response (CSRF protection) +- `nonce` required in OIDC flows; validated against ID token `nonce` claim +- State and nonce must be cryptographically random per request + +### Grant Types +- Authorization Code + PKCE is the preferred/required grant for interactive flows +- Implicit grant is forbidden for new designs +- Client Credentials only allowed for confidential clients (service-to-service) +- Resource Owner Password Credentials (ROPC) grant: only allowed if explicitly justified and approved; flag always + +### Token Storage +- Tokens must NEVER be stored in SharedPreferences without encryption +- Token cache must use Android Keystore-backed encryption +- Tokens must NEVER be written to logs, even at DEBUG level + +### CAE / Continuous Access Evaluation +- Designs affecting token issuance or consumption must address CAE claims challenges +- `xms_cc` claim handling required if the app is CAE-capable + +## Red Flags — Auto-escalate to 🔴 + +- Implicit grant flow proposed for any new feature +- ROPC grant proposed without explicit architectural justification +- Token passed in URL query parameters (visible in logs/referer headers) +- `code_challenge_method=plain` used anywhere +- State or nonce absent from interactive flows +- Token storage in unencrypted SharedPreferences or plain file +- Tokens logged at any log level + +## Yellow Flags — 🟡 Raise for Discussion + +- Non-standard token lifetime proposed (shorter or longer than defaults without justification) +- RT rotation omitted or described as "optional" +- Missing description of how RT expiry is handled in silent flows +- New grant type introduced without comparison to existing grant types +- CAE not mentioned in a flow that issues or validates access tokens + +## Questions to Generate + +- If the doc describes token storage: "Where are tokens persisted and what encryption mechanism is used? Is Android Keystore involved?" +- If the doc describes an interactive auth flow: "Is PKCE enforced? Is `state` validated on callback?" +- If the doc introduces new token types or lifetimes: "What is the justification for the proposed token lifetime? How does this interact with CAE?" +- If the doc touches refresh logic: "Is RT rotation enforced on every redemption? What happens when the RT expires mid-session?" +- If the doc involves redirect URIs: "How are redirect URIs validated? Is package/signature validation in place for broker flows?" diff --git a/.github/skills/architect-reviewer/references/telemetry-compliance-lens.md b/.github/skills/architect-reviewer/references/telemetry-compliance-lens.md new file mode 100644 index 00000000..847a8ba6 --- /dev/null +++ b/.github/skills/architect-reviewer/references/telemetry-compliance-lens.md @@ -0,0 +1,62 @@ +# Telemetry & Compliance Lens + +This lens checks for required telemetry instrumentation, PII handling, and compliance requirements in Android Identity Platform design docs. + +## What to Check + +### Required Telemetry Coverage +- Every new auth flow or operation must emit a telemetry span covering: start, success, and failure +- Failure paths must emit distinct error codes / sub-error codes (not just a generic failure signal) +- New flows must specify: span name, relevant attributes/dimensions, and success/failure signal names +- Existing telemetry spans being modified must document what changes and backward compatibility of dashboards/alerts + +### Span & Signal Naming +- Span names must follow the established pattern for the repo (check existing spans in the codebase) +- Error codes must be unique and searchable in Kusto (`android_spans` table) +- New error codes must not collide with existing ones — verify against the existing error code registry + +### PII Handling (Required) +- User identifiers (UPN, email, OID, TID) must be scrubbed or hashed before being emitted in telemetry +- Device identifiers must follow the platform's PII guidelines (device ID hashing) +- `Logger` class (not `android.util.Log`) must be used for all logging +- Sensitive values (tokens, passwords, certificate private keys) must NEVER appear in telemetry or logs +- Design must explicitly state which attributes in new telemetry events are PII and how they're handled + +### Compliance Gates +- **GDPR**: Any new telemetry data collected from EU users must be assessed for GDPR relevance — consent model, data retention period +- **FedRAMP / GCC High**: Features targeting government cloud (GCC, GCC High, DoD) must not emit data to non-FedRAMP-approved endpoints +- **SOC2**: Security-relevant events (auth success, auth failure, token issuance, account removal) must be auditable + +### Supportability +- New features must emit enough telemetry to diagnose customer-reported issues without requiring a debug build +- Error paths must be diagnosable from Kusto: correlate a customer incident → find the span → identify root cause +- Silent failure modes (places where the feature fails but emits no signal) are a supportability gap → 🟡 + +### Alerting +- High-impact new flows should have a corresponding alert on failure rate spike +- If the design introduces a new critical path (e.g., new broker IPC call in the auth critical path), a latency SLA should be defined + +## Red Flags — Auto-escalate to 🔴 + +- No telemetry section in the design for a new user-facing feature +- PII (UPN, email, device ID) emitted in raw form in telemetry events +- Tokens or credentials present in any log or telemetry event +- `android.util.Log` used instead of the team's `Logger` class +- New flow that is completely unobservable (no success/failure signal) + +## Yellow Flags — 🟡 Raise for Discussion + +- Telemetry section present but failure paths not covered (only success signal described) +- Error codes not specified (generic failure signal only) +- PII handling acknowledged but hashing/scrubbing mechanism not described +- No alerting proposed for high-impact new flows +- New government cloud scenario without FedRAMP/GCC compliance analysis +- Supportability story not discussed (how would on-call diagnose a customer issue with this feature?) + +## Questions to Generate + +- If the doc introduces a new auth flow: "What telemetry spans are emitted? What are the success and failure signals? Are error codes specific enough to diagnose customer issues from Kusto?" +- If telemetry attributes include user data: "Which attributes in the new telemetry events contain PII? How are they scrubbed or hashed before emission?" +- If the design modifies an existing telemetry schema: "Do changes to telemetry attributes break existing Kusto queries or dashboards? Is there a migration plan?" +- If the design adds a new critical path: "Is there a latency SLA for this new path? What alert will fire if the error rate spikes?" +- If the doc targets enterprise customers: "Has this feature been assessed for FedRAMP / GCC High compliance requirements?" diff --git a/.github/skills/architect-reviewer/references/threat-model-lens.md b/.github/skills/architect-reviewer/references/threat-model-lens.md new file mode 100644 index 00000000..90c153b2 --- /dev/null +++ b/.github/skills/architect-reviewer/references/threat-model-lens.md @@ -0,0 +1,67 @@ +# Threat Model Lens + +This lens checks whether the design adequately addresses security threats and attack surfaces for the Android Identity Platform. + +## Reuse Existing Threat-Model Skill + +- Use `.github/skills/threat-modeler/SKILL.md` as the primary mechanism for STRIDE analysis and trust-boundary/data-flow validation. +- This lens is intentionally lightweight and focuses on review-time gating checks. +- If the design includes new components, trust boundaries, IPC channels, or token flows, instruct the reviewer agent to invoke `threat-modeler` for deep analysis. + +## What to Check + +### Threat Model Presence (Mandatory) +- The design MUST include a threat model or security analysis section +- Acceptable forms: STRIDE analysis, trust boundary diagram, explicit listing of attack surfaces and mitigations +- The absence of any threat model section is an automatic 🔴 + +### Trust Boundaries +- Design must identify trust boundaries crossed by the feature (app sandbox → broker sandbox, device → network, MSAL app → Broker) +- Any data crossing a trust boundary must be described with its protection mechanism +- New trust boundaries introduced by the design must be explicitly justified + +### STRIDE Coverage Expectation +- The design must include STRIDE coverage or reference output generated by the `threat-modeler` skill. +- If STRIDE is missing or partial, request a `threat-modeler` run before approval. + +### Common Android-Specific Threats + +- **Intent Sniffing**: Implicit intents carrying tokens or auth codes can be intercepted — explicit intents or content providers required +- **Screenshot / Screen Overlay**: Auth UI must be protected against overlay attacks (FLAG_SECURE where appropriate) +- **Exported Activities**: Any Activity handling auth callbacks must validate the incoming intent carefully +- **Content Provider Leakage**: Content providers used for IPC must require broker signature permission, not just `android:exported="false"` +- **Logcat Leakage**: Tokens or authorization codes written to Logcat are visible to any app on a debug/rooted device +- **WebView Token Theft**: If WebView is used, JavaScript injection paths must be considered +- **PRT Theft**: Primary Refresh Token is extremely sensitive — any design touching PRT issuance, storage, or redemption requires extra scrutiny + +### Data Classification +- Access Tokens → Sensitive; encrypted at rest, never logged +- Refresh Tokens → Highly Sensitive; encrypted at rest, never transmitted over plain HTTP, never logged, never returned to calling app in brokered flows +- Primary Refresh Tokens (PRT) → Critical; must remain inside Broker process, never surfaced to MSAL/OneAuth +- User PII (UPN, display name) → Sensitive; cannot appear in logs without scrubbing + +## Red Flags — Auto-escalate to 🔴 + +- No threat model or security analysis section in the design +- PRT accessed or transmitted outside the Broker process boundary +- Implicit intent used to carry tokens or authorization codes +- Token or auth code written to Logcat at any log level +- TLS not specified for any new network call +- New content provider or exported Activity without permission requirements described +- New scope or privilege level introduced without Elevation of Privilege analysis + +## Yellow Flags — 🟡 Raise for Discussion + +- Threat model present but only covers happy-path (no adversarial scenarios) +- STRIDE not explicitly applied and no `threat-modeler` output referenced +- Screenshot/overlay attack not discussed for new auth UI surfaces +- Retry/DoS resilience not addressed for new network calls +- Audit logging present but PII scrubbing strategy not described + +## Questions to Generate + +- If no threat model section: "There is no threat model or security analysis in this design. What is the attack surface and what mitigations are in place?" +- If the design passes tokens across process boundaries: "How are tokens protected when crossing the trust boundary between [component A] and [component B]? What prevents interception or tampering?" +- If the design adds a new IPC endpoint or exported component: "How is caller identity validated on this new endpoint? What prevents a malicious app from invoking it?" +- If the design involves PRT: "What prevents PRT from being surfaced outside the Broker process? What is the blast radius if this component is compromised?" +- If the design involves WebView: "How is JavaScript injection risk mitigated in this WebView usage? Is the WebView URL-allowlisted?"