System Requirements Document for cookie-roblox

1. Introduction

cookie-roblox is a web-based Roblox cookie refresher tool. It gives a single operator a browser interface for running the operator's own supplied Python refresh logic against Roblox's authentication endpoints: obtain an X-CSRF-TOKEN, generate an authentication ticket, redeem that ticket for a newly issued .ROBLOSECURITY cookie, and log out the old cookie session.

The product intent is instrumentation, not a friendly SaaS product. The operator is an Indonesian-speaking power user who already owns working refresh code and wants it exposed as a web tool they can drive from a browser: paste an existing .ROBLOSECURITY cookie, watch the four-stage pipeline execute under semaphore throttling, and receive the fresh cookie — or a precise, colour-coded outcome explaining why the refresh could not complete (invalid cookie, moderated/banned account, rate limiting, or a network error).

The audience is that single operator. There is no multi-tenant administration, no team collaboration, and no account system: the tool is a personal utility whose value is a legible, trustworthy readout of a throttled multi-stage auth pipeline.

2. System Overview

cookie-roblox is delivered as a small web application with two first-party pages and one backend service.

• Landing is the anonymous public entry surface. It explains what the tool does, who it is for, and the four-stage refresh workflow before any cookie is submitted.
• Refresh is the working surface. The operator submits and normalizes a .ROBLOSECURITY cookie, runs the supplied refresh flow, and reads the resulting success, invalid-cookie, moderated-account, rate-limit, or network-error outcome.
• Backend service executes the supplied Roblox flow: CSRF-token retrieval, authentication-ticket generation, ticket redemption for a new cookie, and logout of the old session. It enforces semaphore throttling and the Retry-After wait on HTTP 429.

Actors:

• Cookie Refresher Operator — the only accepted active human persona. Pastes an existing .ROBLOSECURITY cookie, runs the refresh, and receives the newly issued cookie or a failure outcome.
• Roblox authentication endpoints (auth.roblox.com) — external provider surfaces owned by Roblox. They issue the CSRF token, the authentication ticket, the new .ROBLOSECURITY cookie, and the moderation/invalid-cookie signals. They are not first-party pages and are not built by this product.

Current scope covers the refresh lifecycle and its four named outcomes. Out of scope for the current horizon: account registration, multi-user management, cookie storage or history, scheduled/batch refreshing, and any Roblox capability beyond the supplied CSRF → ticket → redeem → logout flow.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The product owns two first-party pages (Landing, Refresh) and one backend service. All Roblox authentication work is provider-owned: the backend calls auth.roblox.com and reports what the provider returns. The product never impersonates Roblox, never issues cookies itself, and never claims authority over Roblox account state.

Access ownership. Both pages are reachable without an application account (access_requirement: none). The operator's identity in this product is the Roblox cookie they paste, not a first-party login. No application-owned identity, session, or account management is introduced, because no accepted journey requires durable actor-specific state to be privately owned or resumed — each refresh is a self-contained operation whose only durable artifact is the new cookie the operator copies out.

Current vs. future boundary. Current: the four-stage refresh pipeline, semaphore throttling, Retry-After handling, and the four named outcomes. Future (not built now, not on any current page): anything the operator has not accepted — persistence of cookies, refresh history, scheduling, or multi-account handling.

Sensitive-input boundary. The .ROBLOSECURITY cookie is a credential. It is submitted by the operator, used for the duration of the refresh, and returned as a new value. The product does not persist it beyond the request lifecycle.

2b. Source Content Inventory

The authoritative reference directive is the operator's own supplied Python code (get_csrf_token, get_auth_ticket, redeem_auth_ticket, logout_session, refresh_cookie_logic), declared with uses: [content_source, feature_reference] and authority: authoritative. The verified factual content it supplies is preserved below.

Endpoint and header facts

Outcome and control facts

• CSRF stage: HTTP 429 → read Retry-After (default 18) and retry; missing x-csrf-token → cookie may be invalid.
• Ticket stage: HTTP 429 → retry after Retry-After (default 18); HTTP 403 with an error message containing User is moderated → account banned/moderated; HTTP 401 → cookie invalid; rbx-authentication-ticket header present → ticket; HTTP 200 → ticket is the response text; other status → ticket failure.
• Redeem stage: HTTP 429 → retry after Retry-After (default 18); new cookie parsed from Set-Cookie via \.ROBLOSECURITY=(.*?); or from the response cookie jar; no new cookie → redeem failure.
• Logout stage: request_with_retry('POST', url, headers, cookies, max_retries=3, timeout=30); returns True on success, False on exception.
• refresh_cookie_logic return contract: (new_cookie, is_invalid, should_retry, is_moderated) — success (new_cookie, False, False, False); invalid cookie (None, True, False, False); retryable (None, False, True, False); moderated (None, False, False, True).
• Cookie normalization: clean_cookie(old_cookie) is applied before the flow begins.
• Throttling: every network call is wrapped in AUTH_SEMAPHORE so the operator's own IP is not flooded.
• Request settings: timeout=30, impersonate="chrome110", proxies=get_thread_proxy().

2c. Page Content and Component Coverage

Landing

• Information / state: what the tool does (refresh a Roblox .ROBLOSECURITY cookie), who it is for (a single operator running their own refresh flow), and the four-stage pipeline it will run — 01 CSRF → 02 TICKET → 03 REDEEM → 04 LOGOUT. States: default (static explanation), no loading or error state of its own.
• Primary action: MULAI REFRESH — enters the Refresh workspace. Supporting action: none required; the page is explanatory.
• Domain entities: the four pipeline stages (CSRF, Ticket, Redeem, Logout) as named, ordered steps; the .ROBLOSECURITY cookie as the input the operator will supply.
• Component responsibilities:
  • Hero headline block: REFRESH COOKIE ROBLOX in Archivo 800, flush-left, stacked across three lines, spanning columns 1–8, with a 4px vertical red rule at its left edge.
  • Machine manifest column (columns 9–12): right-aligned mono list CSRF · TICKET · REDEEM · LOGOUT, each with a small outlined square.
  • Primary button: MULAI REFRESH, solid Swiss red, yellow hairline focus ring, with mono caption 18s retry window.
  • Pipeline band: the 4-step numbered band, outlined squares, becoming a vertical numbered list below 768px.
  • Hairline baseline grid drawn behind the hero only.
• States: loading — not applicable (static entry). Empty — not applicable. Success — not applicable. Error — not applicable. Recovery — not applicable. The page's only transition is navigation into Refresh.

Refresh

• Information / state: the submitted cookie (normalized), the current pipeline stage and its completion state, the remaining Retry-After seconds when throttled, and the terminal outcome. States: idle (no cookie submitted), running (a stage active), waiting (429 countdown in progress), success (new cookie issued), invalid cookie, moderated account, network error.
• Primary action: submit the .ROBLOSECURITY cookie and run the refresh. Supporting actions: copy the newly issued cookie; retry after a retryable failure; start a new refresh with a different cookie.
• Domain entities: .ROBLOSECURITY cookie (input and output), X-CSRF-TOKEN, authentication ticket, pipeline stage (CSRF / Ticket / Redeem / Logout), outcome type (success / invalid / moderated / rate-limited / network error), Retry-After interval.
• Component responsibilities:
  • Cookie input: single-line/multiline field with 2px radius, accepting the raw .ROBLOSECURITY value; normalization applied on submit.
  • Refresh control: solid Swiss red primary button; disabled while a refresh is running.
  • Pipeline band: four outlined squares that fill solid Swiss red as each stage completes; the current stage's square pulses once per second.
  • Retry-After bar: full-width red-to-yellow horizontal fill with remaining seconds printed in mono at its right cap; under prefers-reduced-motion it becomes a static number updating each second.
  • Cookie output block: full-bleed monospace block on #1A1A1C, tabular JetBrains Mono numerals, hairline top rule, copy button docked to the right edge that flips to solid yellow on success.
  • Outcome signal block: solid red block for invalid cookie, solid yellow block for moderated account, grey block for network error — each with an all-caps 0.16em label and a short mono explanation.

• States: loading — pipeline band shows the active stage, refresh control disabled. Empty — no cookie submitted, output block absent. Success — new cookie rendered in the output block, all four squares filled red, copy control available. Error — the matching signal block is shown with its mono explanation; retryable failures expose a retry action. Recovery — after a retryable failure the operator can retry the same cookie or submit a different one; after invalid or moderated outcomes the operator can start a new refresh.

3. Functional Requirements

FR-1 — Web-based refresher tool (explicit) As a Cookie Refresher Operator, I should be able to use a web-based tool for refreshing Roblox cookies, so that I can run my refresh flow from a browser instead of a local script.

• Trigger: operator opens the application.
• Observable result: the Landing page presents the tool and its workflow; the Refresh page accepts a cookie and runs the flow.
• Access state: both pages reachable without an application account.
• Failure/recovery: not applicable at this level.
• Continuation: operator proceeds to submit a cookie.

FR-2 — Use the operator's own supplied code as the refresh basis (explicit) As a Cookie Refresher Operator, I should have the refresh logic built on my own supplied code, so that the tool behaves exactly like the flow I already trust.

• Trigger: any refresh run.
• Observable result: the executed flow is the supplied refresh_cookie_logic sequence — clean_cookie normalization, CSRF retrieval, ticket generation, ticket redemption, and logout — with the supplied headers, endpoints, and return contract.
• Access state: not applicable.
• Failure/recovery: deviations from the supplied flow are defects, not alternatives.
• Continuation: the flow proceeds stage by stage.

FR-3 — Obtain the X-CSRF-TOKEN (explicit) As a Cookie Refresher Operator, I should have the tool obtain an X-CSRF-TOKEN from Roblox, so that the subsequent authenticated calls can be made.

• Trigger: refresh run begins after cookie normalization.
• Input: the normalized .ROBLOSECURITY cookie.
• Observable result: a CSRF token is retrieved from the x-csrf-token response header of a POST to https://auth.roblox.com/v2/logout made without an X-CSRF-TOKEN header, so Roblox rejects the request (403) and returns the token without performing a logout.
• Access state: no application account required.
• Failure/recovery: if no x-csrf-token is returned, the cookie may be invalid; the flow then checks cookie validity — if valid, the run is retryable; if not, the cookie is reported invalid.
• Continuation: on success, proceed to ticket generation.

FR-4 — Generate an authentication ticket (explicit) As a Cookie Refresher Operator, I should have the tool generate a Roblox authentication ticket, so that a fresh cookie can be issued.

• Trigger: CSRF token obtained.
• Input: the normalized cookie and the CSRF token.
• Observable result: a POST to https://auth.roblox.com/v1/authentication-ticket/ with the X-CSRF-TOKEN header, the cookie, and an empty JSON body returns the ticket from the rbx-authentication-ticket response header, or from the response body text on HTTP 200.
• Access state: no application account required.
• Failure/recovery: HTTP 401 → cookie invalid, no retry; HTTP 403 with an error message containing User is moderated → account banned/moderated, no retry; other non-success status → ticket failure, retryable.
• Continuation: on success, proceed to redemption.

FR-5 — Redeem the ticket for a new cookie (explicit) As a Cookie Refresher Operator, I should have the tool redeem the authentication ticket to obtain a new .ROBLOSECURITY cookie, so that I receive a refreshed credential.

• Trigger: authentication ticket obtained.
• Input: the ticket and the CSRF token.
• Observable result: a POST to https://auth.roblox.com/v1/authentication-ticket/redeem with body {"authenticationTicket": ticket} and the RBXAuthenticationNegotiation: 1 header returns a new cookie, parsed from the Set-Cookie header via \.ROBLOSECURITY=(.*?); or from the response cookie jar.
• Access state: no application account required.
• Failure/recovery: if no new cookie is present, the redeem failed and the run is retryable.
• Continuation: on success, the new cookie is presented to the operator and the old session is logged out.

FR-6 — Log out the old cookie session (explicit) As a Cookie Refresher Operator, I should have the tool log out the old cookie session, so that the superseded credential is not left active.

• Trigger: the refresh flow reaches the logout stage.
• Input: the old cookie and the CSRF token.
• Observable result: a POST to https://auth.roblox.com/v2/logout with the X-CSRF-TOKEN header and the old cookie, retried up to 3 times with a 30-second timeout, returns success or failure.
• Access state: no application account required.
• Failure/recovery: an exception during logout returns failure; the logout result does not invalidate an already-issued new cookie.
• Continuation: the run completes and the outcome is reported.

FR-7 — Report an invalid cookie (explicit) As a Cookie Refresher Operator, I should be told when my cookie is invalid, so that I know the refresh cannot succeed and must supply a different cookie.

• Trigger: CSRF retrieval fails and cookie validation reports invalid, or the ticket stage returns HTTP 401.
• Observable result: the run returns (None, is_invalid=True, should_retry=False, is_moderated=False) and the Refresh page shows a solid red signal block with an all-caps label and a short mono explanation.
• Access state: no application account required.
• Failure/recovery: no retry is offered for this outcome; the operator starts a new refresh with a different cookie.
• Continuation: operator submits a new cookie.

FR-8 — Report a moderated/banned account (explicit) As a Cookie Refresher Operator, I should be told when the account is moderated or banned, so that I understand the refresh is blocked by Roblox account state rather than by my cookie.

• Trigger: the ticket stage returns HTTP 403 with an error message containing User is moderated.
• Observable result: the run returns (None, is_invalid=False, should_retry=False, is_moderated=True) and the Refresh page shows a solid yellow signal block with an all-caps label and a short mono explanation.
• Access state: no application account required.
• Failure/recovery: no retry is offered for this outcome.
• Continuation: operator may start a new refresh with a different cookie.

FR-9 — Handle rate limiting with Retry-After (explicit) As a Cookie Refresher Operator, I should have the tool wait and retry when Roblox rate-limits a request, so that a temporary 429 does not fail my refresh.

• Trigger: any stage receives HTTP 429.
• Input: the Retry-After response header, defaulting to 18 seconds when absent.
• Observable result: the tool waits the indicated interval and retries the same request; the Refresh page shows a full-width red-to-yellow countdown bar with the remaining seconds printed in mono at its right cap.
• Access state: no application account required.
• Failure/recovery: under prefers-reduced-motion the bar becomes a static number updating each second with no bar animation.
• Continuation: the retried request proceeds through the pipeline.

FR-10 — Handle network errors (explicit) As a Cookie Refresher Operator, I should be told when a network error prevents the refresh, so that I can distinguish a connectivity problem from a cookie or account problem.

• Trigger: an exception occurs while contacting Roblox during any stage.
• Observable result: the stage reports the error and the run is treated as retryable where the flow's return contract says so; the Refresh page shows a grey signal block with an all-caps label and a short mono explanation.
• Access state: no application account required.
• Failure/recovery: the operator can retry the same cookie.
• Continuation: operator retries or starts a new refresh.

FR-11 — Provide a Roblox .ROBLOSECURITY cookie (required_inference) As a Cookie Refresher Operator, I should be able to provide my Roblox .ROBLOSECURITY cookie to the tool, so that the refresh flow has the credential it operates on.

• Trigger: operator opens the Refresh page.
• Input: the raw .ROBLOSECURITY value.
• Observable result: the cookie is accepted, normalized via clean_cookie, and used as the flow's input.
• Access state: no application account required.
• Failure/recovery: an empty or unusable submission does not start a run.
• Continuation: the refresh run begins.

FR-12 — Execute the supplied flow in the backend (required_inference) As a Cookie Refresher Operator, I should have the backend execute the CSRF, ticket, redemption, and logout calls, so that the browser does not have to make cross-origin calls to Roblox directly.

• Trigger: operator starts a refresh.
• Observable result: the backend performs the four stages with the supplied endpoints, headers, timeouts (timeout=30), impersonate="chrome110", and proxy resolution, and returns the outcome to the page.
• Access state: no application account required.
• Failure/recovery: backend failures surface as the corresponding outcome on the Refresh page.
• Continuation: the outcome is rendered.

FR-13 — Semaphore-throttled refresh requests (required_inference; explicit constraint) As a Cookie Refresher Operator, I should have my refresh requests throttled by a semaphore, so that my own IP is not flooded.

• Trigger: any outbound Roblox request.
• Observable result: each network call is executed under AUTH_SEMAPHORE, limiting concurrent in-flight requests.
• Access state: no application account required.
• Failure/recovery: throttling delays rather than fails requests.
• Continuation: the request proceeds when the semaphore permits.

FR-14 — Retry 429 responses after the Retry-After interval (required_inference; explicit constraint) As a Cookie Refresher Operator, I should have HTTP 429 responses retried after the Retry-After interval, defaulting to 18 seconds, so that rate limiting is respected rather than hammered.

• Trigger: HTTP 429 from any stage.
• Observable result: the tool waits the interval (default 18 seconds) and retries.
• Access state: no application account required.
• Failure/recovery: repeated 429s repeat the wait-and-retry loop.
• Continuation: the request proceeds once accepted.

4. User Personas

Cookie Refresher Operator

Product context. The operator is a single Indonesian-speaking power user who already maintains working Python code for refreshing Roblox cookies. They supplied that code — get_csrf_token, get_auth_ticket, redeem_auth_ticket, logout_session, and refresh_cookie_logic — as the authoritative basis for the tool, and they want it exposed as a web interface they can drive from a browser. They are comfortable reading status codes, headers, and token values, and they treat the tool as instrumentation rather than a consumer product.

Primary goal. Turn an existing, possibly stale .ROBLOSECURITY cookie into a freshly issued one, using their own flow, without flooding their own IP and without losing visibility into which stage is running or why a run failed.

Distinct accepted responsibilities.

• Supply the .ROBLOSECURITY cookie that the flow operates on, and have it normalized before use.
• Start the refresh and observe the four-stage pipeline (CSRF → Ticket → Redeem → Logout) as it executes.
• Read and act on the terminal outcome: copy the new cookie on success, or respond to an invalid-cookie, moderated-account, rate-limit, or network-error result.
• Decide whether to retry the same cookie or start over with a different one.

Relevant inputs and decisions. The cookie value itself; the decision to run a refresh; the decision to retry after a retryable failure versus abandoning the cookie; the decision to copy the new cookie out of the tool.

Interactions with other accepted participants. The operator's only counterparty is Roblox's authentication endpoints, which are provider-owned and not a persona. The operator initiates every call; Roblox returns the CSRF token, the ticket, the new cookie, or a moderation/invalid signal. The operator never negotiates with another human actor.

Observable success. The Refresh page shows all four pipeline squares filled solid red and a new .ROBLOSECURITY value rendered in the monospace output block, ready to copy. Failure is equally legible: a red block for an invalid cookie, a yellow block for a moderated account, a grey block for a network error, and a red-to-yellow countdown bar whenever the tool is waiting out a Retry-After interval.

What makes this role distinct. The operator is simultaneously the author of the logic and the consumer of its output. They are not asking the tool to decide anything on their behalf — they are asking it to run their own sequence faithfully, throttle it, and report precisely. That is why the interface is a status console rather than a guided wizard.

5. Core User Flows

Flow 1 — Understand the tool before submitting a cookie

1. The Cookie Refresher Operator opens the application and lands on Landing.
2. The page presents the headline REFRESH COOKIE ROBLOX, the machine manifest column listing CSRF · TICKET · REDEEM · LOGOUT, and the primary button MULAI REFRESH with its mono caption 18s retry window.
3. The operator reads the four-stage pipeline band and understands that the tool will run CSRF retrieval, ticket generation, ticket redemption, and logout.
4. The operator activates MULAI REFRESH and arrives at Refresh.
5. Next step: submit a cookie (Flow 2).

Flow 2 — Refresh a valid cookie successfully

1. On Refresh, the Cookie Refresher Operator pastes an existing .ROBLOSECURITY value into the cookie input.
2. The operator starts the refresh. The refresh control becomes disabled and the pipeline band shows stage 01 CSRF as the active step.
3. The backend normalizes the cookie via clean_cookie and, under AUTH_SEMAPHORE, POSTs to https://auth.roblox.com/v2/logout without an X-CSRF-TOKEN header. Roblox rejects the request with 403 and returns the x-csrf-token header. Stage 01 CSRF fills solid red.
4. The backend POSTs to https://auth.roblox.com/v1/authentication-ticket/ with the CSRF token and the cookie. Roblox returns the ticket in the rbx-authentication-ticket header (or as the response body on HTTP 200). Stage 02 TICKET fills solid red.
5. The backend POSTs to https://auth.roblox.com/v1/authentication-ticket/redeem with {"authenticationTicket": ticket} and the RBXAuthenticationNegotiation: 1 header. Roblox returns a new .ROBLOSECURITY cookie in Set-Cookie. Stage 03 REDEEM fills solid red.
6. The backend POSTs to https://auth.roblox.com/v2/logout with the CSRF token and the old cookie, retrying up to 3 times. Stage 04 LOGOUT fills solid red.
7. Observable result: the Refresh page renders the new cookie in the full-bleed monospace output block with tabular numerals, and the copy control docked to its right edge.
8. The operator activates the copy control; it flips to solid yellow to confirm the copy.
9. Next step: the operator uses the new cookie outside the tool, or starts a new refresh with a different cookie.

Flow 3 — Recover from a rate-limited stage

1. During any stage of a refresh on Refresh, Roblox responds with HTTP 429.
2. The backend reads the Retry-After header, defaulting to 18 seconds when absent, and waits.
3. Observable result: the Refresh page shows a full-width red-to-yellow countdown bar filling left to right, with the remaining seconds printed in mono at its right cap. The active pipeline square continues to pulse once per second.
4. Under prefers-reduced-motion, the bar is replaced by a static number that updates each second with no bar animation.
5. When the interval elapses, the backend retries the same request and the pipeline continues from that stage.
6. Next step: the run proceeds to its terminal outcome (Flow 2, 4, 5, or 6).

Flow 4 — Handle an invalid cookie

1. On Refresh, the operator submits a cookie that Roblox no longer accepts.
2. The CSRF stage returns no x-csrf-token, and cookie validation reports the cookie invalid; or the ticket stage returns HTTP 401.
3. Observable result: the run ends with is_invalid = True and should_retry = False. The Refresh page shows a solid red signal block with an all-caps label and a short mono explanation.
4. No retry is offered for this outcome.
5. Next step: the operator starts a new refresh with a different cookie (Flow 2).

Flow 5 — Handle a moderated or banned account

1. On Refresh, the operator submits a cookie for an account that Roblox has moderated.
2. The ticket stage returns HTTP 403, and the response body's errors array contains a message with User is moderated.
3. Observable result: the run ends with is_moderated = True and should_retry = False. The Refresh page shows a solid yellow signal block with an all-caps label and a short mono explanation.
4. No retry is offered for this outcome.
5. Next step: the operator may start a new refresh with a different cookie.

Flow 6 — Recover from a network error or retryable failure

1. During any stage of a refresh on Refresh, a network exception occurs, or a stage returns a non-success status that the flow's return contract marks retryable (should_retry = True).
2. Observable result: the Refresh page shows a grey signal block with an all-caps label and a short mono explanation, and the pipeline band shows which stage did not complete.
3. The operator chooses to retry the same cookie or to start a new refresh with a different one.
4. On retry, the backend re-runs the flow from the beginning under AUTH_SEMAPHORE.
5. Next step: the run proceeds to its terminal outcome (Flow 2, 4, or 5).

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. Muse: Josef Müller-Brockmann. Headline: Swiss geometric rigour for a machine that rotates secrets.

Mode. Dark only. No light mode is specified.

Colour tokens by role

Body text is #F2F0EA at 16px on #0E0E0F (contrast ≈ 16:1). #8A8A8F is never placed below 14px. No gradients, no glass, no shadows.

Typography

• Headings: Archivo, weights 700/800, tracking -0.03em, flush-left ragged-right. Sentence case for prose headings; all-caps at 0.16em letterspacing for micro-labels and pipeline step names.
• Body: Archivo.
• Token/cookie output: JetBrains Mono 14–16px with tabular numerals.
• Modular scale (1.333): 14 / 16 / 21 / 28 / 38 / 50 / 67, clamped mobile→desktop.
• Display headline: clamp(40px, 7vw, 88px).
• Section rule labels: 12px caps.

Shape language. Hard edges only: 0px radius everywhere except a 2px radius on inputs. Geometry as content — filled circles, quarter-circle arcs, and a 4px red rule under every section. Nothing is rounded, nothing floats, nothing is soft.

Layout. A strict 12-column modular grid with 24px gutters and a visible hairline baseline behind the hero. Everything left-aligned, asymmetric balance: the display headline occupies columns 1–8 while columns 9–12 hold a vertical stack of status numerals. The pipeline is a horizontal 4-step band that becomes a vertical numbered list below 768px. The cookie output is a full-width monospace block with a copy control pinned to its right edge.

Imagery. No photography, no illustration, no 3D. Imagery is diagrammatic: a geometric hero composition of a large red circle, a yellow quarter-arc, and stacked black rules — a schematic, not a picture — plus pictogram-style step icons drawn as 2px strokes. The product's own data (status codes, ticket state, timestamps) is the visual material.

Avoid. Blue or indigo primaries and any white/near-white ground; gradient blobs, glassmorphism, soft shadows, rounded cards, hover-lift grids; centred headline + subtext + button hero composition; Inter, Roboto, Poppins, system-ui or any neutral template sans; illustration, photography, 3D or character art; bouncy, springy or parallax motion; anything that delays a status readout; green "success" clichés — success is red-filled pipeline completion, not a checkmark badge; emoji, mascots or playful copy in the operator console.

7. Signature Design Concept

The pipeline band as the product's spine.

The Landing hero is a full-bleed ink-black field. The headline REFRESH COOKIE ROBLOX is set in Archivo 800 at clamp(40px, 7vw, 88px), flush-left, spanning columns 1–8 and breaking across three lines with the words stacked, not wrapped. To its left edge sits a 4px vertical red rule running the full height of the headline block. Columns 9–12 hold a right-aligned vertical column of mono metadata — CSRF · TICKET · REDEEM · LOGOUT, each with a small outlined square — that reads like a machine manifest. Beneath the headline, pinned to the baseline of the grid, a single red filled button MULAI REFRESH with a yellow hairline focus ring and a mono caption 18s retry window. No gradient, no blob, no centred stack, no product screenshot.

The signature move carries into the Refresh workspace: the same four outlined squares become the live pipeline band, filling solid Swiss red as each stage completes, with the current stage's square pulsing once per second. The Retry-After wait is visualised as a full-width red-to-yellow horizontal fill bar with the remaining seconds printed in mono at its right cap, so the 429 constraint becomes the interface's most distinctive moment. The cookie output is a full-bleed monospace block on #1A1A1C with tabular JetBrains Mono numerals, a hairline top rule, and a copy button docked to the right edge that flips to solid yellow on success. Status outcomes are colour-coded as Swiss signal blocks: solid red for invalid cookie, solid yellow for moderated account, grey for network error — each with an all-caps 0.16em label and a short mono explanation.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject. The geometric hero composition: a large red circle, a yellow quarter-arc, and stacked black rules, with the stacked REFRESH COOKIE ROBLOX headline and the mono machine manifest column.
• Input → transformation → outcome thesis. The operator's attention moves from the headline (what the tool is) to the manifest column (what it will do) to the MULAI REFRESH button (how to start). The transformation is a single restrained state change — the button's yellow hairline focus ring on focus — and the outcome is arrival at the Refresh workspace. No accepted behaviour is added; the hero only recomposes the accepted entry content.
• Motion vocabulary. Restrained and mechanical: state transitions are 120–180ms linear fades and instant colour swaps. No easing theatrics, no parallax. The only loop in the product is the 18-second Retry-After countdown on the Refresh page, rendered as a red-to-yellow horizontal bar that fills left to right with the seconds printed in mono beside it. Pipeline steps flip from outline to solid red as each stage completes.
• Composed first frame. Ink-black field, hairline baseline grid behind the hero, the 4px vertical red rule at the headline's left edge, the three-line stacked headline in columns 1–8, the mono manifest column in columns 9–12, and the red MULAI REFRESH button pinned to the grid baseline with its 18s retry window caption.
• Reduced-motion state. prefers-reduced-motion removes the countdown bar animation on the Refresh page, replacing it with a static number that updates each second. The hero itself is static in all modes.

9. Non-Functional Requirements

NFR-1 — Semaphore throttling (explicit) All outbound Roblox requests must be executed under AUTH_SEMAPHORE so that the operator's own IP is not flooded. Rationale: the operator's supplied code wraps every network call in the semaphore, and the constraint is stated explicitly in the authoritative source.

NFR-2 — Retry-After compliance (explicit) On HTTP 429, the tool must wait the Retry-After interval, defaulting to 18 seconds when the header is absent, before retrying. Rationale: explicit hard constraint in the authoritative source.

NFR-3 — Request timeout (explicit) Outbound Roblox requests use a 30-second timeout. Rationale: every supplied call passes timeout=30.

NFR-4 — Logout retry budget (explicit) The logout call is retried up to 3 times. Rationale: the supplied logout_session uses request_with_retry(..., max_retries=3, timeout=30).

NFR-5 — Credential handling (required_inference) The .ROBLOSECURITY cookie is a credential. It is used for the duration of a refresh and returned as a new value; the product does not persist it beyond the request lifecycle. Rationale: the supplied flow treats the cookie as a per-run input and output, and no accepted requirement introduces storage.

NFR-6 — Readable text and controls at every viewport (explicit, creative direction) Headlines, wordmarks, labels, numbers, card text, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, with no other element covering any part of them. Rationale: explicit creative-direction constraint.

NFR-7 — Reduced-motion support (explicit, creative direction) Under prefers-reduced-motion, the Retry-After countdown bar becomes a static number that updates each second with no bar animation. Rationale: explicit creative-direction constraint.

NFR-8 — Contrast (explicit, creative direction) Body text #F2F0EA on #0E0E0F yields a contrast ratio of approximately 16:1. Muted grey #8A8A8F is never used below 14px. Rationale: explicit creative-direction constraint.

10. Tech Stack

• Frontend: React (web), styled to the creative direction in Section 6.
• Backend: Python with FastAPI, hosting the supplied refresh flow — get_csrf_token, get_auth_ticket, redeem_auth_ticket, logout_session, and refresh_cookie_logic — as the authoritative logic.
• HTTP client: the supplied flow's request library with impersonate="chrome110", timeout=30, and proxy resolution via get_thread_proxy().
• Concurrency control: a semaphore (AUTH_SEMAPHORE) guarding every outbound Roblox request.
• Storage: none required for the current horizon; the cookie is not persisted beyond the request lifecycle.
• Packaging: Docker with docker-compose, running the frontend and the backend service.

11. Assumptions and Constraints

Assumptions

• A1 (required_inference): The operator has an existing Roblox .ROBLOSECURITY cookie to submit.
• A2 (required_inference): The backend can reach auth.roblox.com and any proxy returned by get_thread_proxy().
• A3 (required_inference): The operator is the only user of the tool; no concurrent multi-operator coordination is required.
• A4 (required_inference): The supplied Python functions are the authoritative implementation of the refresh flow and are ported into the backend without changing their endpoint, header, or return-contract semantics.

Constraints

• C1 (explicit): Refresh requests must be throttled by a semaphore so the operator's own IP is not flooded.
• C2 (explicit): On HTTP 429, wait the Retry-After interval (default 18 seconds) before retrying.
• C3 (explicit): The CSRF token is obtained by POSTing to https://auth.roblox.com/v2/logout without an X-CSRF-TOKEN header, relying on Roblox's 403 rejection to return the token without performing a logout.
• C4 (explicit): The ticket stage treats HTTP 401 as an invalid cookie and HTTP 403 with a User is moderated error message as a moderated account.
• C5 (explicit): The redeem stage parses the new cookie from the Set-Cookie header via \.ROBLOSECURITY=(.*?);, falling back to the response cookie jar.
• C6 (explicit): The logout call is retried up to 3 times with a 30-second timeout.
• C7 (explicit, creative direction): No blue or indigo primaries, no white/near-white ground, no gradients, glassmorphism, soft shadows, rounded cards, or hover-lift grids; no Inter, Roboto, Poppins, or system-ui; no illustration, photography, 3D, or character art; no bouncy, springy, or parallax motion; no green "success" clichés; no emoji, mascots, or playful copy in the operator console.
• C8 (explicit, creative direction): Readable text and controls stay whole at every viewport; imagery, decoration, and motion may be cropped or bled but must never cover readable text or a control.

Future (not current scope)

• Persisting refreshed cookies or refresh history.
• Scheduled or batch refreshing.
• Multi-account handling.
• Any Roblox capability beyond the supplied CSRF → ticket → redeem → logout flow.

12. Glossary

• .ROBLOSECURITY — Roblox's session cookie. The input to and output of the refresh flow.
• CSRF token (X-CSRF-TOKEN) — A token Roblox requires on authenticated POST requests. Obtained by POSTing to https://auth.roblox.com/v2/logout without the header, so Roblox rejects the request with 403 and returns the token in the x-csrf-token response header.
• Authentication ticket — A short-lived credential issued by https://auth.roblox.com/v1/authentication-ticket/, returned in the rbx-authentication-ticket response header or as the response body on HTTP 200.
• Redeem — Exchanging an authentication ticket at https://auth.roblox.com/v1/authentication-ticket/redeem for a newly issued .ROBLOSECURITY cookie.
• Logout — POSTing to https://auth.roblox.com/v2/logout with the CSRF token and the old cookie to end the superseded session.
• AUTH_SEMAPHORE — The semaphore that limits concurrent outbound Roblox requests so the operator's own IP is not flooded.
• Retry-After — The response header on HTTP 429 indicating how long to wait before retrying; defaults to 18 seconds when absent.
• clean_cookie — The normalization applied to the submitted cookie before the flow begins.
• refresh_cookie_logic — The supplied top-level flow returning (new_cookie, is_invalid, should_retry, is_moderated).
• Moderated account — A Roblox account blocked from authentication, signalled by HTTP 403 with an error message containing User is moderated.
• Invalid cookie — A cookie Roblox no longer accepts, signalled by a missing CSRF token with failed validation, or by HTTP 401 at the ticket stage.
• Pipeline band — The four-step numbered band (01 CSRF → 02 TICKET → 03 REDEEM → 04 LOGOUT) whose squares fill solid Swiss red as each stage completes.