UNPKG

@crossplatformai/skills

Version:

Reusable Agent Skills for CrossPlatform.ai projects.

github.com/crossplatformai/framework

crossplatformai/framework

77 lines (56 loc) • 5.49 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
# Automation Auth Reference Use this reference when planning, building, or shipping AI/automation authentication flows for local, development, or staging environments. For mechanics (ports, startup commands, DB queries, automation selectors, and per-surface timing), see `fast-auth-playbook.md`. ## Standard Identity - Standard automation user: `automation@local.test`. - This identity is for local/test automation only. Do not reuse it as a production user or as proof of production authentication behavior. - App repositories own product-specific user IDs, display names, roles, seeds, session response shapes, cookies, localStorage, AsyncStorage, Electron storage, and UI routes. ## Visible Auth Proof - Prefer the real visible UI for sign-in, sign-up, email verification, profile access, and auth UX proof. - If visible auth UX is the proof, require UI navigation and form submission wherever feasible. Local/test acceleration may remove external waits such as verification-code or magic-link delivery, but it must not skip the UI behavior being demonstrated unless the handoff explicitly justifies that shortcut. - For verification-code or magic-link delivery delays, local/test acceleration may retrieve the active code or link only to paste or use it inside the automation flow. The assistant must not print, log, screenshot, summarize, commit, or hand off the code or link. - Evidence should be user-visible proof such as the route or screen, visible authenticated content, `automation@local.test` when displayed by the app, and a clean final state with no blocking overlay, permission prompt, debug menu, or keyboard. - Do not treat direct session, cookie, storage, or bootstrap seeding as visible auth proof when auth UX itself is the behavior being demonstrated. ## Setup Shortcut - For tests where auth is setup rather than the behavior under proof, use `POST ${API_URL}/api/test-auth/bootstrap` when the app provides it. - Treat bootstrap as a local/test setup shortcut, not a user-login bypass for production or visible auth proof. Handoffs must state why auth is setup rather than the behavior under proof. - Browser, desktop, and mobile harnesses may seed the storage layers their surfaces actually read after bootstrap, but app-specific storage keys and adapters stay in the app repo guidance. ## Shared Helper - Use `@crossplatformai/auth/test-auth` for shared automation auth constants and pure helper functions. - The shared helper owns the standard automation email, environment gate, test-auth secret derivation, timing-safe validation, and standard bootstrap request headers. - App wrappers may preserve existing behavior such as returning `null` when local env is missing or returning `false` when auth is disabled. ## Secret Derivation - Derive the test-auth secret with HKDF-SHA256. - `inputKeyMaterial = APP_KEY`. - `salt = APP_SLUG`. - `info = ${APP_SLUG}:test-auth`. - `length = 32` bytes. - Output encoding is `base64url`. - Do not add or document a shared fixed login code. - Do not copy derived secrets into docs, handoffs, logs, screenshots, tests, commit messages, or chat output. ## Adapter Expectations - Web adapters usually call the bootstrap endpoint through `API_URL`, then seed the browser auth state the web app actually reads. - Desktop adapters usually need the desktop-origin cookie plus renderer localStorage and Electron IPC or preload storage when the app reads those layers. - Mobile adapters usually use the platform's test storage or AsyncStorage adapter after bootstrap, according to the mobile app guidance. - Keep adapter instructions generic in shared skills. Keep concrete origins, ports, routes, storage keys, cookie names, IPC channels, and OTP pasteboard details in the target app's `AGENTS.md` or docs. ## Desktop/Electron Attach Caveat - Desktop/Electron verification must attach to the already-running app window through the repo-specific Playwright Electron/CDP target when the handoff requires desktop proof. - `DESKTOP_DEV_PORT` is the renderer dev server port. `DESKTOP_CDP_PORT` is the Electron CDP / remote-debugging attach port for Playwright Electron and OpenCode MCP when a repo supports stable visible dev attach. - Concrete CDP port values live in the target repo's `.env` or repo guidance, not this shared reference. - Configured OpenCode MCP endpoints for Electron CDP may be present even when the matching desktop app is not currently running. Start the matching app before attaching. - DevTools-only targets are not app-window proof. - If no app-window debug target is attachable, the repo-specific target points at the wrong port, a debug-port collision prevents attachment, or only DevTools is exposed, report desktop verification as skipped or unverified for that unit. - Do not infer desktop auth proof from web or mobile evidence. Do not relaunch the app, change debug ports, or claim desktop verification unless the handoff or target repo guidance explicitly approves that action. ## Sensitive Material Rules Never expose any of the following in chat, files, commit messages, logs, screenshots, handoffs, test artifacts, or console summaries: - OTPs or verification codes - magic links - tokens - cookies - auth headers - storage dumps - database URLs - `APP_KEY` values - auth bypass secrets - derived test-auth secrets If a QA or e2e command is blocked by missing env, report only the missing variable names. Do not invent secrets and do not edit `.env` unless the user explicitly asks.