stegasoo/frontends/api/API_UPDATE_SUMMARY_V3.2.0.md

API Update Summary for v3.2.0

Overview

The FastAPI REST API has been updated to align with Stegasoo v3.2.0's breaking changes:

1. Removed date dependency - No date_str field in requests
2. Renamed day_phrase → passphrase - Updated all request/response models
3. Updated generation - Now generates single passphrase instead of daily phrases

Breaking Changes

Request Model Changes

1. EncodeRequest & EncodeFileRequest

Before (v3.1.0):

class EncodeRequest(BaseModel):
    message: str
    reference_photo_base64: str
    carrier_image_base64: str
    day_phrase: str  # ← Changed to passphrase
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    date_str: Optional[str] = None  # ← REMOVED
    embed_mode: EmbedModeType = "lsb"

After (v3.2.0):

class EncodeRequest(BaseModel):
    message: str
    reference_photo_base64: str
    carrier_image_base64: str
    passphrase: str = Field(description="Passphrase (v3.2.0: renamed from day_phrase)")
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    # date_str removed in v3.2.0
    embed_mode: EmbedModeType = "lsb"
    dct_output_format: DctOutputFormatType = "png"
    dct_color_mode: DctColorModeType = "grayscale"

2. DecodeRequest

Before (v3.1.0):

class DecodeRequest(BaseModel):
    stego_image_base64: str
    reference_photo_base64: str
    day_phrase: str  # ← Changed to passphrase
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    embed_mode: ExtractModeType = "auto"

After (v3.2.0):

class DecodeRequest(BaseModel):
    stego_image_base64: str
    reference_photo_base64: str
    passphrase: str = Field(description="Passphrase (v3.2.0: renamed from day_phrase)")
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    embed_mode: ExtractModeType = "auto"

3. GenerateRequest

Before (v3.1.0):

class GenerateRequest(BaseModel):
    use_pin: bool = True
    use_rsa: bool = False
    pin_length: int = Field(default=6, ge=MIN_PIN_LENGTH, le=MAX_PIN_LENGTH)
    rsa_bits: int = Field(default=2048)
    words_per_phrase: int = Field(default=3, ge=MIN_PHRASE_WORDS, le=MAX_PHRASE_WORDS)

After (v3.2.0):

class GenerateRequest(BaseModel):
    use_pin: bool = True
    use_rsa: bool = False
    pin_length: int = Field(default=6, ge=MIN_PIN_LENGTH, le=MAX_PIN_LENGTH)
    rsa_bits: int = Field(default=2048)
    words_per_passphrase: int = Field(
        default=DEFAULT_PASSPHRASE_WORDS,  # = 4, was 3
        ge=MIN_PASSPHRASE_WORDS,
        le=MAX_PASSPHRASE_WORDS,
        description="Words per passphrase (v3.2.0: default increased to 4)"
    )

Response Model Changes

1. GenerateResponse

Before (v3.1.0):

class GenerateResponse(BaseModel):
    phrases: dict[str, str]  # Monday -> phrase, Tuesday -> phrase, etc.
    pin: Optional[str] = None
    rsa_key_pem: Optional[str] = None
    entropy: dict[str, int]

After (v3.2.0):

class GenerateResponse(BaseModel):
    passphrase: str = Field(description="Single passphrase (v3.2.0: no daily rotation)")
    pin: Optional[str] = None
    rsa_key_pem: Optional[str] = None
    entropy: dict[str, int]
    # Legacy field for compatibility
    phrases: Optional[dict[str, str]] = Field(
        default=None,
        description="Deprecated: Use 'passphrase' instead"
    )

2. EncodeResponse

Before (v3.1.0):

class EncodeResponse(BaseModel):
    stego_image_base64: str
    filename: str
    capacity_used_percent: float
    date_used: str
    day_of_week: str
    embed_mode: str
    output_format: str = "png"
    color_mode: str = "color"

After (v3.2.0):

class EncodeResponse(BaseModel):
    stego_image_base64: str
    filename: str
    capacity_used_percent: float
    embed_mode: str
    output_format: str = "png"
    color_mode: str = "color"
    # Legacy fields (no longer used in crypto)
    date_used: Optional[str] = Field(
        default=None,
        description="Deprecated: Date no longer used in v3.2.0"
    )
    day_of_week: Optional[str] = Field(
        default=None,
        description="Deprecated: Date no longer used in v3.2.0"
    )

Endpoint Changes

1. POST /encode

Before (v3.1.0):

{
  "message": "Secret message",
  "reference_photo_base64": "...",
  "carrier_image_base64": "...",
  "day_phrase": "apple forest thunder",
  "date_str": "2025-01-15",
  "pin": "123456",
  "embed_mode": "lsb"
}

After (v3.2.0):

{
  "message": "Secret message",
  "reference_photo_base64": "...",
  "carrier_image_base64": "...",
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "embed_mode": "lsb"
}

2. POST /decode

Before (v3.1.0):

{
  "stego_image_base64": "...",
  "reference_photo_base64": "...",
  "day_phrase": "apple forest thunder",
  "pin": "123456",
  "embed_mode": "auto"
}

After (v3.2.0):

{
  "stego_image_base64": "...",
  "reference_photo_base64": "...",
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "embed_mode": "auto"
}

3. POST /generate

Response Before (v3.1.0):

{
  "phrases": {
    "Monday": "apple forest thunder",
    "Tuesday": "banana river lightning",
    ...
  },
  "pin": "123456",
  "rsa_key_pem": null,
  "entropy": {
    "phrase": 33,
    "pin": 20,
    "rsa": 0,
    "total": 53
  }
}

Response After (v3.2.0):

{
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "rsa_key_pem": null,
  "entropy": {
    "passphrase": 44,
    "pin": 20,
    "rsa": 0,
    "total": 64
  },
  "phrases": null
}

4. POST /encode/multipart

Form Fields Before (v3.1.0):

• day_phrase (required)
• date_str (optional)
• reference_photo (file)
• carrier (file)
• ...

Form Fields After (v3.2.0):

• passphrase (required) ← renamed from day_phrase
• reference_photo (file)
• carrier (file)
• ... (date_str removed)

Response Headers Before (v3.1.0):

X-Stegasoo-Date: 2025-01-15
X-Stegasoo-Day: Wednesday
X-Stegasoo-Capacity-Percent: 25.5
X-Stegasoo-Embed-Mode: lsb

Response Headers After (v3.2.0):

X-Stegasoo-Capacity-Percent: 25.5
X-Stegasoo-Embed-Mode: lsb
X-Stegasoo-Output-Format: png
X-Stegasoo-Color-Mode: color
X-Stegasoo-Version: 3.2.0

New Status Endpoint Information

GET /

Added to response:

{
  "version": "3.2.0",
  ...
  "breaking_changes": {
    "date_removed": "No date_str parameter needed - encode/decode anytime",
    "passphrase_renamed": "day_phrase → passphrase (single passphrase, no daily rotation)",
    "format_version": 4,
    "backward_compatible": false
  }
}

Migration Guide for API Clients

1. Update Request Bodies

Find and replace in client code:

// Before
{
  day_phrase: "apple forest thunder",
  date_str: "2025-01-15"
}

// After
{
  passphrase: "apple forest thunder mountain"
}

2. Update Response Handling

Before:

const response = await fetch('/encode', {
  method: 'POST',
  body: JSON.stringify({
    message: "secret",
    day_phrase: "words",
    date_str: "2025-01-15",
    ...
  })
});

const data = await response.json();
console.log(data.date_used);  // "2025-01-15"
console.log(data.day_of_week);  // "Wednesday"

After:

const response = await fetch('/encode', {
  method: 'POST',
  body: JSON.stringify({
    message: "secret",
    passphrase: "longer words here now",
    // date_str removed
    ...
  })
});

const data = await response.json();
// date_used and day_of_week are null in v3.2.0

3. Update Generate Endpoint Usage

Before:

const creds = await fetch('/generate', {
  method: 'POST',
  body: JSON.stringify({ use_pin: true })
}).then(r => r.json());

// Use Monday's phrase
const mondayPhrase = creds.phrases['Monday'];

After:

const creds = await fetch('/generate', {
  method: 'POST',
  body: JSON.stringify({ use_pin: true })
}).then(r => r.json());

// Use single passphrase
const passphrase = creds.passphrase;

4. Update Multipart Requests

Before (JavaScript fetch):

const formData = new FormData();
formData.append('day_phrase', 'apple forest thunder');
formData.append('date_str', '2025-01-15');
formData.append('reference_photo', refPhotoFile);
formData.append('carrier', carrierFile);
formData.append('message', 'secret');
formData.append('pin', '123456');

const response = await fetch('/encode/multipart', {
  method: 'POST',
  body: formData
});

After (JavaScript fetch):

const formData = new FormData();
formData.append('passphrase', 'apple forest thunder mountain');
// date_str removed
formData.append('reference_photo', refPhotoFile);
formData.append('carrier', carrierFile);
formData.append('message', 'secret');
formData.append('pin', '123456');

const response = await fetch('/encode/multipart', {
  method: 'POST',
  body: formData
});

Testing Checklist

Endpoints to Test

• GET / - Returns v3.2.0 with breaking_changes info
• GET /modes - Returns mode information
• POST /generate - Returns single passphrase
• POST /encode - Works without date_str
• POST /encode/file - Works without date_str
• POST /decode - Works without date_str
• POST /encode/multipart - Accepts passphrase instead of day_phrase
• POST /decode/multipart - Accepts passphrase instead of day_phrase
• POST /compare - Still works
• POST /will-fit - Still works
• POST /image/info - Still works
• POST /extract-key-from-qr - Still works

Validation Tests

• Reject requests with day_phrase field (should get validation error)
• Reject requests with date_str field (should be ignored or error)
• Accept requests with passphrase field
• Generate response includes passphrase field
• Generate response has phrases as null
• Encode response has date_used and day_of_week as null
• Multipart encode works with new field names
• Response headers updated correctly

OpenAPI/Swagger Documentation

The FastAPI auto-generated documentation (/docs and /redoc) will automatically reflect the changes:

1. Models updated - Request/response schemas show new field names
2. Descriptions updated - Field descriptions mention v3.2.0 changes
3. Examples updated - Interactive API explorer uses new field names

Users can browse to /docs to see the updated API specification.

Backward Compatibility

Breaking Change: API v3.2.0 is NOT backward compatible with v3.1.0

Clients using the old API will encounter:

1. Validation errors - Missing required passphrase field
2. Unexpected responses - phrases field will be null
3. Changed behavior - Date fields no longer populated

Migration Timeline Recommendation

1. Deploy v3.2.0 API to staging
2. Update client applications to use new field names
3. Test thoroughly with staging API
4. Deploy v3.2.0 API to production
5. Notify users of breaking changes

Alternatively, run v3.1.0 and v3.2.0 APIs side-by-side on different paths:

• /api/v3.1/ - Old API
• /api/v3.2/ - New API

Constants Updates

Used in validation:

from stegasoo.constants import (
    MIN_PASSPHRASE_WORDS,  # = 3
    MAX_PASSPHRASE_WORDS,  # = 12
    DEFAULT_PASSPHRASE_WORDS,  # = 4 (increased from 3)
)

Error Messages

All error messages updated:

• "day_phrase is required" → "passphrase is required"
• References to "phrase" now mean "passphrase"

Implementation Status

✅ All request models updated ✅ All response models updated ✅ All endpoints updated ✅ Multipart endpoints updated ✅ Status endpoint shows breaking changes ✅ Constants imported correctly ✅ Error handling updated ✅ No references to day_phrase in user-facing text ✅ No date_str parameters accepted

Ready for deployment!